API Requests Authentication

To call and authenticate an API request, you need to obtain an access token. The only supported provider of access tokens for ONE is Keycloak.

Supported client authentication methods

There are multiple methods of getting an access token from Keycloak. The recommended approach is to set up a service account client in the Ataccamaone Keycloak realm and set its Client Authenticator to one of the following options:

Client ID and Secret
JSON Web Token (Signed JWT)

Using one of these authentication methods, you can get access tokens from Keycloak when authenticating API requests.

You can also use the Basic HTTP Authentication Scheme. However, due to insufficient security, it is not recommended for use in production environments.

For in-depth information about the underlying authentication protocols, see the official OAuth 2.0 and OpenID Connect documentation.

Create a service account client in Keycloak

To authenticate API requests, you need a dedicated Keycloak client with a service account enabled. This allows the client to obtain access tokens using the client credentials grant. For more information, see the Keycloak documentation, Using a service account.

To set up a service account client in Keycloak:

Log in to your Keycloak Admin Console as the ataccamaone realm admin.
Select the Ataccama ONE realm: ataccamaone.
Create a new OpenID Connect client:
1. Select Clients > Create client.
2. Configure client settings:
  - Client type: OpenID Connect.
  - Client ID: A unique identifier for your service account client.
3. Select Next.
4. Configure authentication:
  - Client authentication: Enable this option.
  - Authorization: Leave turned off.
  - Authentication flow:
    
    Enable Service accounts roles.
    
    Turn off Standard flow.
    
    Leave other fields turned off.
5. Select Next.
6. Keep the Login settings screen as it is, and select Save.
To configure the credentials of the client:
1. Go to the Credentials tab.
2. Select your preferred option from the Client Authenticator list. For recommended options, see Supported client authentication methods. For more information, see the Keycloak documentation, Confidential client credentials.
On the Service Account Roles tab, assign the roles required for your API endpoint. This depends on which roles you set up as required for the endpoint in the server configuration. The required roles are configured in:
- For Ataccama Online Services: The Security Filter of the HTTP Dispatcher Configuration, as an Intercept URL setting. For more information, see HTTP Dispatcher, Security Filter section.
- For MDM (Native services, REST API, and Online services): mdm-server/etc/application.properties. For more information, see MDM Server Application Properties.

Get an access token from Keycloak

To obtain an access token from Keycloak, you need to invoke a REST URL as a POST request and submit the client credentials with it. The REST URL to invoke is https://<keycloak>/realms/ataccamaone/protocol/openid-connect/token.

You also need to set the grant_type parameter to "client_credentials" as per the OAuth 2.0 specification.

Client ID and Secret

When using Client ID and Secret authentication, the request must include client_id and client_secret.

Example curl POST request

curl --request POST \
  --url "https://<keycloak>/realms/ataccamaone/protocol/openid-connect/token" \
  --data "grant_type=client_credentials" \
  --data "client_id=<keycloak_client_with_service_account>" \
  --data "client_secret=<client_secret>"

Example response

{
    "access_token":"<access token>",
    "expires_in":"<expiry of the token in seconds>",
    "refresh_expires_in":"<expiry of the refresh token in seconds, usually set to 0>",
    "token_type":"Bearer",
}

JSON web token (signed JWT)

When using Certificate Signed JSON Web Token (Signed JWT) authentication, the request must include client_assertion and client_assertion_type.

If you choose this credential type, you also have to manage how your tokens are signed (either by certificate or client secret). For more information, see the Keycloak documentation, Confidential client credentials, Signed JWT section.

Example curl POST request

curl --request POST \
    --url "https://<keycloak>/realms/ataccamaone/protocol/openid-connect/token" \
    --data "grant_type=client_credentials" \
    --data "client_id=<keycloak_client_with_service_account>" \
    --data "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
    --data "client_assertion=<a JWT that contains information necessary for client authentication>"

The client_assertion must contain the following required claims:

Claim Description

Claim	Description
iss (Issuer)	Contains the `client_id` of the OAuth client.
exp (Expiration time)	Time after which the JWT is no longer accepted.
aud (Audience)	A value that identifies the authorization server as the intended audience. The authorization server must verify that it is the intended audience for the token. The audience should be the URL of the authorization server’s token endpoint (in our case: `https://<keycloak>/realms/ataccamaone/protocol/openid-connect/token`).
jti (A unique ID of the JWT)	A unique identifier of the token. Must be a unique value for each request.

iss (Issuer)

Contains the client_id of the OAuth client.

exp (Expiration time)

Time after which the JWT is no longer accepted.

aud (Audience)

A value that identifies the authorization server as the intended audience. The authorization server must verify that it is the intended audience for the token.

The audience should be the URL of the authorization server’s token endpoint (in our case: https://<keycloak>/realms/ataccamaone/protocol/openid-connect/token).

jti (A unique ID of the JWT)

A unique identifier of the token. Must be a unique value for each request.

The response to the request would be the same as in the previous example.

Example response

{
    "access_token":"<access token>",
    "expires_in":"<expiry of the token in seconds>",
    "refresh_expires_in":"<expiry of the refresh token in seconds, usually set to 0>",
    "token_type":"Bearer",
}

Authenticate an API request

Use the access token (bearer token) obtained in the previous step to authenticate your API requests. Provide the token in the Authorization: Bearer header of the HTTP request.

For example, you could now provide the obtained access token in the Authorization header in the GraphQL playground that comes preconfigured with ONE. For more information and examples of GraphQL queries, see ONE API.

Was this page useful?