Client management

In addition to human users, machine-to-machine (M2M) clients (such as Access Decision Service (ADS) or a CI/CD pipeline) can access Authorization Hub and its API programmatically. You manage these clients through Keycloak.

Access Keycloak

Follow the steps below to access the Keycloak administration console:

1. Append ../auth/admin/hub/console/ to your Authorization Hub deployment URL.
2. Log in to your Authorization Hub account if you haven't already done so.
3. The Keycloak console will open with the Authorization Hub realm selected by default.

You are now ready to perform any of the procedures listed below.

warning

Axiomatics supports only the Keycloak configuration options documented in the Authorization Hub documentation. Use of other configuration settings may lead to unsupported behavior.

Manage client access

Follow the instructions below to configure client access rights within Keycloak.

warning

Do not edit or delete predefined clients, as they are essential for the correct operation of Authorization Hub.

• Grant access
• Revoke access

1. In the Keycloak menu, click Clients under the Manage section.

2. Click Create client and complete the setup following the Managing OpenID Connect and SAML ClientsOpens in a new tab instructions in the Keycloak documentation.

   During the Capability config step, verify the following parameters are set:

   Parameter	Value
   Client authentication	On
   Service accounts roles	Checked

3. Click Next, then Save, and return to the clients list.

4. Open the client you just created from the list and select the Credentials tab.

5. Copy the Client Secret and use it to configure your external service to authenticate against the Authorization Hub API.

1. In the Keycloak menu, click Clients under the Manage section.

2. Click the Client ID of the client you want to block.

3. Toggle the Enabled switch on the top right of the interface.

4. Click Disable in the pop-up to confirm.

   The client is now disabled. Access will be revoked once the access token expires (typically within five minutes).

   tip

   To revoke access immediately, remove the client from its assigned projects. Read the Projects section for details.

Obtain an access token

M2M clients authenticate using the OAuth 2.0 Client Credentials grant. Use the following token endpoint:

https://<authorization-hub-url>/auth/realms/hub/protocol/openid-connect/token

Replace <authorization-hub-url> with your Authorization Hub deployment URL and use the Client ID and Client Secret from the Manage client access section above.

• curl
• Postman

curl -X POST "https://<authorization-hub-url>/auth/realms/hub/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-client-secret>"

note

The steps below use Postman as an example. Adapt them for your HTTP client of choice.

1. Create a new request and set the method to POST.

2. Enter the token endpoint URL in the address bar.

3. Go to the Body tab and select x-www-form-urlencoded.

4. Add the following key-value pairs:

   Key	Value
   grant_type	client_credentials
   client_id	<your-client-id>
   client_secret	<your-client-secret>

5. Click Send and copy the access_token value from the response.

The response is a JSON object. The access_token field contains the Bearer token used to authenticate subsequent API requests. The expires_in field indicates the token's validity period.

Token expiration

Access token lifespan is determined by the Access Token Lifespan setting, configured either at the individual client level or inherited from the Hub realm in Keycloak. Track the expires_in value in the token response and re-authenticate proactively before the token expires to avoid interrupted API calls.

tip

Request a new token in advance of expiration rather than waiting for a 401 Unauthorized response. A common pattern is to refresh the token when less than a set threshold of its lifespan remains.

Add client to a project

Before a client can access project resources, it must be added as a project member by a Project admin through the Authorization Hub interface.

Follow the steps in the Projects section. When selecting members, switch to the Clients tab to locate your client and assign it a project role.

note

Authorization Hub lists every client you create in Keycloak, except for the predefined clients it needs to operate. A new client appears the next time the client list is loaded. Through the API, clients are listed by GET /api/principal/clients and added to projects the same way as users. Read Projects and users.

The project role determines what the client can do through the API. Read API permissions for details.

Use the API

Authorization Hub exposes interactive API documentation through Swagger UI. Use the links below to explore available endpoints while signed in to Authorization Hub:

• http(s)://<authorization-hub-url>/api/hub-service/swagger-ui/index.html
• http(s)://<authorization-hub-url>/api/adm-service/swagger-ui/index.html

note

Swagger UI is read-only (Try it out is disabled), and the users and clients endpoints under /api/principal are not listed. Read the API reference for the complete list of endpoints, required headers, permissions, and errors.

To authenticate API requests, include the access token obtained in the Obtain an access token section as a Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Requests to the content of a project, such as attributes, policies, or domains, must also identify the project in the X-Project-Id header, and the client must be a member of that project with a role that allows the request:

X-Project-Id: <project-id>

Read the API overview and API permissions for details.

• curl
• Postman

Pass the headers with the -H flag. For example, to list the projects the client belongs to:

curl -X GET "https://<authorization-hub-url>/api/projects" \
  -H "Authorization: Bearer <access_token>"

To list the attributes of a project:

curl -X GET "https://<authorization-hub-url>/api/dictionary/attributes" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Project-Id: <project-id>"

note

The steps below use Postman as an example. Adapt them for your HTTP client of choice.

1. Open your request in Postman.
2. Go to the Authorization tab.
3. Set Auth Type to Bearer Token.
4. Paste the access_token value in the Token field.
5. For requests to the content of a project, go to the Headers tab and add the X-Project-Id header with your project ID as the value.