Manage the privileges associated with credentials for system API access

Systems access APIs via client credentials, which are associated with clients in the authorisation server. Clients may have associated

  • client scopes, which control the endpoints (authoring, staging and production) the credentials have access to;
  • and, Service Account Roles which dictate the specific authorities granted to the client for these endpoints.

Users with service desk level permissions can manage client scopes and service account roles for a client.

  1. Log in to the Administration Console
  2. Click on the “Clients” tab on the menu on the left

3. Search for the client you wish to manage the client scope for

4. Click on the Client ID you wish to manage the the client scope for

5. Select the “Client Scopes” tab

6. In the “Default Client Scopes”,

a) set the scopes you wish to give the client by selecting the scope from “Available Client Scopes”, then clicking “Add selected >>”

Client scopes can be added to the “Assigned Default Client Scopes” to give the client access to endpoints secured by the authorisation server. In the default realm configuration the sensible options are the

  • authoring (read/write) terminology server,
  • production (read only, including staging) server,
  • syndication server.

However whether all of these servers are deployed in your deployment and hence available to configure will depend on the specifics of your deployment.

The corresponding “Available Default Client Scopes” for these servers are

  • “authoring-server”
  • “production-server”
  • “syndication-server”

Any combination of these can be added/omitted to grant/deny the client access to these server’s endpoints. Which to add will depend on the use case for the specific client being managed, however a good rule is to grant only the minimum necessary access to perform the functions the client needs to perform.

b) remove scopes by selecting the scope from “Assigned Default Client Scopes”, then clicking “<< Remove selected”

7. Now go to the “Service Account Roles” tab

8. In the “Realm Roles”

a) To add roles, select the role you wish to assign to the client from the “Available Roles” and click “Add selected >>”. You can repeat this for multiple roles.

For example, if you are a setting up client credentials for a remote server to retrieve syndication resources, you will need to add the “Syndication read” role (as well as the syndication-server scope in Step 6).

b) To remove roles, select the role you wish to remove from the client from the “Assigned Roles” and click “<< Remove selected”. You can repeat this for multiple roles

No action is required for “Client Roles”, the appropriate client roles will be assigned based on their configuration in the selected realm roles.

Once you have generated client credentials, these can be used to retrieve an OAuth2 token using a request to the token endpoint, which will be of the form [authorisation-base-url]/auth/admin/[realm_name]/token relative to the authorisation server’s URL base and authorisation realm name.