If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

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.

There are multiple methods to obtain an access token from Keycloak. The recommended best practice is to set up a service account enabled 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)

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

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

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

Each Keycloak client has a built-in service account which, if enabled, allows it to obtain an access token. For more information, see the official Keycloak documentation, Using a service account.

To set up a service account client in Keycloak:

Log in to Keycloak Admin Console as the ataccamaone realm admin.
Create a new OpenID Connect client:
1. In the left pane, in Configure, select Clients.
2. Select Create.
3. Leave Client type set to OpenID Connect.
4. Enter a unique identifier in the Client ID field.
5. Select Save. This action creates the client and brings you to the Settings tab of the client.
On the Settings tab, do the following:
1. From the Access Type list, select confidential.
2. Switch the Standard Flow Enabled toggle to Off.
3. Switch Direct Access Grants Enabled toggle to Off.
4. Switch the Service Accounts Enabled toggle to On.
5. Select Save.
Configure the credentials of the client to your preferred option on the Credentials tab. For more information, see the official Keycloak documentation, Confidential client credentials.
To access a specific API, add the necessary roles to your service account client on the Service Account Roles tab. This depends on which roles you set up as required for the endpoint in the server configuration.

For example, for Ataccama Online Services the roles needed would be defined in the Security Filter of the HTTP Dispatcher Configuration as an Intercept URL setting. For an example, see HTTP Dispatcher, Security Filter section.

For MDM (Native services, REST API, and Online services), you can define the required roles in mdm-server/etc/application.properties. For more information, see API Endpoint Required Role Configuration in 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 Example

A request for the Client ID and Secret Client authentication type must include a client_id and client_secret for authentication.

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) example

A request for the Certificate Signed JSON Web Token (Signed JWT) authentication type must include a client_assertion and client_assertion_type for authentication.

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 official 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)	This 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. This needs to be a unique value for each request.

iss (Issuer)

This 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. This needs to 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

You can now use the access token (bearer token) you would get in any of the previous examples to authenticate an API request. You should 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?