Application Management (KeyAccess)

Overview

Before an application can connect to the KeySquare platform using one of the api's, it must be configured in KeyAccess.

KeySquare treats applications and users as 'resources' both capable of connecting to the platform.

Before we get started, ensure that

1. Key UI is up and running (default port = 6500)
2. You are able to login using the admin account (username=admin, password=ksadmin) or any account with role = ADMIN

tip

Update the default admin password by setting KS_WEB_DATA_SERVER_ADMIN_PASSWORD in Web-Data-Server

note

Authentication for Key UI are managed separate to platform permissions in KeyAccess. (details here)

To verify, you have role = ADMIN, look for the Admin section in the sidebar

Please refer to instructions here on how to assign user roles

Register New Application

1. Click on Permissions in the admin side panel
2. Ensure 'Applications' is selected in the top-menu
3. Click on the blue 'New' icon
4. Enter name for your new application e.g. demo
   • We recommend using kebab case for names
   • Note: Names must be 20 characters or less and must be unique across all resources (applications, users, groups etc)
   • Note: Application names cannot be changed once created

Every application is assigned a unique application id.

New Application Group, User, User Group

Follow the same instructions as new application. Simply select the appropriate resource from the top menu.

Publish and Subscription Permissions

A newly created application can connect to the platform, but by default it is not permissioned to subscribe or publish any data.

Ensure you have a good understanding of topic structure before adding/removing permissions.

To manage permission, find your application in the applications table and click 'View Details'

In the detail window

1. Scroll down to Entitlements
2. Pick the appropriate permissions from the series of options.
   1. Type => SUBSCRIBE | PUBLISH
   2. Schema => Dropdown with all available schemas available on platform
   3. Template => Dropdown with all available types for the chosen schema
   4. Source => case sensitive source name that this application should be able to subcribe/publish (matches on topicSource)
      • Default topicSource for publishers is <applicationName>
   5. Group => case sensitive source name that this application should be able to subcribe/publish (matches on topicGroup)
      • Default topicGroup for publishers is 'NONE'
3. Click + to add the permission and hit 'Save Changes'
4. A notification should confirm successful save

tip

1. Use schema and template wildcards sparingly. Whilst this may be convenient, it can make managing permissions difficult in the long run
2. Use Application Groups (or User Groups) to manage permissions if multiple resources need the same permissions.
   1. Create Application Group similar to 'new application'
   2. Update permissions/entitlements as instructed above
   3. Go back and View details for your application and 'Assign this resource to group' you just created
   4. Hit 'Save Changes'

Get an API key

To get an api key for an application or user

1. Click on Permissions in the admin side panel
2. Ensure 'Applications' or 'User' is selected as appropriate in the top-menu
3. Find the application or user in the table and click view detail
4. Scroll down to 'API Keys' section
5. Click 'Generate API Key'
6. Click 'Save Changes'. Note: API key is not persisted until changes are saved

tip

1. In Java the API key can bet set by:
   1. calling setApiKey(apiKey) on KeySessionContext
   2. setting System Property KS_APP_API_KEY=apiKey
2. In Python, it can be set in the constructor of KeySession as application_key=apiKey
3. In Excel, apiKey can set in the ribbon

Assigning user a role

User Groups serve a dual role in permissions. In addition to managing data permissions for group of users, they are also used to manage Key UI permissions

Assuming, there is a user group called 'support'. When a user is assigned to this group, they will:

1. Have role = SUPPORT when they log into Key UI
2. Be able to access any views or workspaces shared with group = 'SUPPORT'

Two user groups are created by default:

1. admin
2. developer

To create new user group, follow the same instructions as new application. Simply select 'User Groups' from the top menu.

To assign a user to a group

1. Click on Permissions in the admin side panel
2. Select 'User' from the top-menu
3. Click 'View Details' in the row of your user
4. Scroll to 'Resource Groups' section
5. Pick the required group from the drop down and hit 'Save Changes'