Skip to main content

Client Credentials

Acquiring the client ID and client secret​

The client ID and the client secret are acquired via the web UI by navigating to the Management API view from the main menu (See figure below). A new client can be registered by clicking the Register new button, which opens a new view where client information can be specified.

If a client is selected from this list, the client can be copied with the use of the Copy button. This will create a new new API client with the same configuration and the currently signed in user as the owner. Pressing the button will automatically open up the editor for the copied API client. The client ID and secret will be generated, upon pressing the Save button in the editor.

A client may be activated/deactivated from the Editor menu for a client.

The client must have a name and a specified owner. The selected owner is considered responsible for the use of the client credentials and the client. The client owner will also act as a contact person regarding the client. Additionally a client’s access should be restricted to a minimal set of namespaces and permissions. The client can also have rules regarding allowed or disallowed IP addresses as well as rate limiting options for API calls.

After saving the new client information a pop-up window will show the newly generated client ID and client secret. (See figure below) By design, the client secret is confidential and will only be shown once. After closing the window the client secret can not be obtained again, but it’s possible to generate and show a new client secret. However, the client ID is not confidential and can be viewed at any time at the Management API view.

Renewing Client Secret​

It is possible to renew the client secret. However, please note that renewing the secret renders old clients immediately as non-functional.

To renew the secret, navigate to the Management API view and select your client on the list. After selecting the client, click the “reset secret” button on the toolbar to reset the secret. The client secret will be regenerated but the client ID will remain unchanged.

Configuring the client​

When creating a new client, it should be configured accordingly in the Trivore Identity Service web UI, which is shown in Figure 3. The web UI has options for namespaces the client is allowed to access as well as the permissions that the client will have.

As noted earlier the client access configuration should follow the principle of least privilege, which means that the client should only have access to the resources that are necessary for it to perform its tasks.

The available API permissions are likely to increase in number along with the number of features in Trivore Identity Service. Maintained list of permissions will not be included in this document. However, the permission required by each resource is listed in the API documentation.

The IP address rules can be used to restrict the source IP addresses where requests are allowed. The IP addresses are entered in CIDR notation format. IP address ranges can easily be converted to CIDR notation format by using a tool found at ipadressguide.com. There are plenty of similar tools freely available.

The IP addresses can be either allowed or restricted. The logic used to evaluate the list of allowed and disallowed IP addresses is quite simple. If there are 'Allowed' rules, the IP address must match at least one of them. If there are 'Disallowed' rules, the IP address must not match any of them.

Rate limiting rules can be set for each HTTP method, with a minimum and maximum artificial delay.

Protection​

It is possible to enable protection for an API client. This prevents accidental modification of the API client. The protection must be disabled before any modification or removal is possible. This protection does not apply to actions performed through APIs. It only applies to actions made through this web user interface. If the user wants to enable the protection they must give a reason for this.

If enabled the figure below will appear in the editor window when trying to edit a protected API client. This will also appear when trying to remove a protected API client.

Export​

Management API clients can be exported from this view. When pressing the Export button, a dialogue will open up with the information in a JSON format. The JSON file will have the following format:

{
    "id" : "5ed64aedc3f8b70e0c6bbb3e",
    "name" : "TestTestTest",
    "clientId" : "7276537982165878",
    "clientSecretEncoded" : "CONCEALED",
    "active" : true,
    "softDeleted" : false,
    "apiPermissions" : [ ],
    "allowedIpRules" : [ ],
    "rateLimitRules" : [ ],
    "meta" : {
    "created" : "2020-06-02T12:49:49.653Z",
    "lastModified" : "2020-06-02T12:49:49.653Z"
    },
    "namespaces" : [ "test001" ],
    "primaryNamespace" : "test001",
    "ownerId" : "85372809@Test 001 (Test)"
}