Client Credentials Grant Type

Each request is accompanied by an access token to ensure validity of the request. Requests are executed in the context of a configured technical user.

For prerequisites to use OAuth 2.0 Authentication, see REST API section in the administration manual.

note

To ensure that credentials and tokens are protected at all times, use HTTPS with OAuth 2.0.

Client Credentials

To retrieve an access token, a POST request has to be sent to the server's "oauth2/token" endpoint where previously provided client credentials (Client ID and Client Secret) have to be provided via the request's Authorization header. Let's have a look at an example request:

Access Token

In order to create an access token, you need to perform a POST request to the token endpoint in the oauth2 servlet.

REQUEST

https://localhost:8000/ADOXX/oauth2/token?grant_type=client_credentials&scope=myScope

The request needs to have the Authorization header set containing the client ID and client secret.

Example Value: Assuming the client ID "client" and the password "secret", the string "client:secret" is constructed and then base64-encoded. The value of the Authorization header is then:

Basic Y2xpZW50OnNlY3JldA==

Example Generation and Setting of the Authorization Header (Java):

String sPath = "https://<SERVER_NAME>:<PORT>/<PRODUCT><VERSION>/oauth2/token?grant_type=client_credentials&scope=myScope";

String sClientID = "client";

String sSecret = "secret";

HttpGet aMethod = new HttpGet (sPath);

String sUnencodedToken = sClientID + ":" + sSecret;

aMethod.addHeader ("Authorization", "Basic " + DatatypeConverter.printBase64Binary (sUnencodedToken.getBytes ()));

The result of this request will be a JSON response of the following form:

RESPONSE

{
  "access_token": "3Ow3o27zWh24q37P4mHQtGf6b-fCraSJj3G34vrt5AM",
  "token_type": "Bearer",
  "expires_in": 1799,
  "scope": "myScope"
}

It contains the generated access token (type bearer), the time in seconds how long the token will still be valid and the scope of the token.

In case of an error (invalid input, expired grant etc.), the response will contain the headers error and error_description with useful information concerning the reason of the failure.

Token Usage

Having a valid access token, you can access information from the ADOXX-based product.

When performing the REST call, you need to add an authorization header of the type of the returned token (e.g. "bearer") passing the access token as value. The REST component will verify the code and log in the corresponding user if successfully verified.

Example Generation and Setting of the Authorization Header (Java):

String sPath = "https://<SERVER_NAME>:<PORT>/<PRODUCT><VERSION>/rest/myEndpoint";

String sAccessToken = "some_token_received";

HttpGet aMethod = new HttpGet (sPath);

aMethod.addHeader ("Authorization", "Bearer " + sAccessToken);