Client Credentials Grant Type
Each request is accompanied by an access token to ensure validity of the request. Requests may be executed in the context of any standard product user.
For prerequisites to use OAuth 2.0 Authentication, see REST API section in the administration manual.
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,
"refresh_token": "SVdQLDjEYfPrHv79KgRqSSAyE_-3b4SEcHlM1Og5KD4"
}
It contains the generated access token (type bearer), the time in seconds how long the token will still be valid and a refresh token, which can be used to generate the next access 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.
Refresh Token
Refreshing tokens is very similar to the previous step of creating an access token based on an authorization code. The difference is only, that we are passing a different grant (refresh token instead of authorization code).
REQUEST
https://localhost:8000/ADOXX/oauth2/token?grant_type=refresh_token&refresh_token=SVdQLDjEYfPrHv79KgRqSSAyE_-3b4SEcHlM1Og5KD4
All the rest (error handling etc.) are the same.
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);