Identity API
Introduction
The Identity API enables authentication for users and applications that want to use APIs from ANVA. We offer an identity provider solution based on OAuth 2.0 and OpenID Connect. In addition to accessing the APIs, our OpenID Connect identity provider also enables integration and single sign-on into other applications.
Grant types
The OpenID Connect identity provider provides support for various grant types. Depending on the application, a particular grant type is more or less appropriate. The grant types supported are the authorization code grant, client credential grant, implicit grant and refresh token grant.
The authorization code grant is recommended for websites and applications where users perform actions themselves and use our APIs. The user logs in to the OpenID Connect identity provider with his account information, and the client application itself does not need to have this account information. If the authorization code grant is used, a refresh token is also provided. Based on the refresh token grant, a new access token can be obtained after validity of the previous one has expired.
The client credential grant is recommended for applications that access our APIs from certain (batch) processes where it is not important that the actions are performed on behalf of specific user.
We also provide support for the implicit grant, but its use is inherently more vulnerable than using the authorization code grant because the access token is shared with the client application via the URI rather than in an encrypted HTTPS body.
Authorization code grant
The authorization code grant consists of executing an authorization request that requests an authorization code. Next, the authorization code can be used to execute a token request that requests an access token.
Authorization request
The authorization request can be composed in the following manner. The requested authorization code will be valid for a maximum of 10 minutes.
Endpoint: /identity/authorize
Method: GET
Query Parameters: The following parameters should be included in the request.
- client_id - The client id of the OpenID Client.
- redirect_uri - A valid redirect URL of the client application that is also registered with the OpenID Client.
- respone_type - The value 'code' must be used for the authorization code grant.
- scope - The desired authorization roles should be added to this parameter. The roles are separated by a space. The roles must also be configured at the OpenID Client.
- state - A value issued by the client application that can be checked when the response is received.
- nonce - A unique value issued by the client application by which the specific response can be recognized.
- max_age - An optional parameter that allows the client application to manage the maximum lifetime of the token, where the maximum lifetime of the access token as configured in the OpenID Client cannot be exceeded.
- response_mode - An optional parameter that allows the client application to control in which format the response is given. The value 'query' (default) ensures the inclusion of the response parameters in the query string of the response. The value 'fragment' ensures the inclusion of the response parameters in the fragment string of the response.
Sample request:
/identity/authorize?response_type=code
&scope=openid Basic
&client_id=92c0a4eb-40be-42a6-9f50-597c86666b7b
&state=Clientapp_XYZ
&redirect_uri=https://clientapp.nl/redirect
&nonce= mgEy0yLZ825W
&max_age=28800
&response_mode=query
Sample response:
https://clientapp.nl/redirect?code=o3ztCK3W8kQxwpts&state= Clientapp_XYZ
Token request
The token request can be composed in the following way.
Endpoint: /identity/token
Method: POST
Headers: The following parameters must be included in the header of the request.
1. Authorization-Basic authorization followed with the Base64-encoded string of the Client ID and Client secret of the OpenID Client. Connect the Client ID and Client secret with ":" and base64-encode the whole thing: base64encode([Client ID]:[Client secret])
Example:
'Authorization':'Basic' OTJjjMGE0ZWItNDBiZS00MmE2LTlmNTAtNTk3Yzg2NjY2YjdiOlBiZGtPSmJ0WGpWVktMQ2hFY2ZybGZ2RFlYUlZ4Vw'
2. Content Type-application/x-www-form-urlencoded.
Example:
'Content-Type':'application/x-www-form-urlencoded'
Request Body: The following parameters must be included in the body of the request.
- grant_type - Contains the value 'authorization_code'.
- redirect_uri - The redirect URI of the client application.
- code - The authorization code previously obtained.
Refresh token grant
The refresh token grant can be used to request a new access token based on a previously obtained refresh token. The token request based on the refresh token grant can be composed in the following way.
Endpoint: /identity/token
Method: POST
Headers: The following parameters must be included in the header of the request.
1. Authorization-Basic authorization followed with the Base64-encoded string of the Client ID and Client Secret of the OpenID Client.
'Example:Authorization':'Basic OTJjMGE0ZWItNDBiZS00MmE2LTlmNTAtNTk3Yzg2NjY2YjdiOlBiZGtPSmJ0WGpWVktMQ2hFY2ZybGZ2RFlYUlZ4Vw'
2. Content Type-application/x-www-form-urlencoded
Example:'Content-Type':'application/x-www-form-urlencoded'
Request Body: The following parameters must be included in the body of the request.
- grant_type - Contains the value 'refresh_token'.
- refresh_token - The previously obtained refresh token.
Client credential grant
This method of authentication can be used outside the context of a use, for example, when two systems interact where it is not important that the actions are performed on behalf of a user.
The token request can be composed in the following way.
Endpoint: /identity/token
Method: POST
Headers: The following parameters must be included in the header of the request.
1. Authorization-Basic authorization followed with the Base64-encoded string of the Client ID and Client Secret of the OpenID Client.
Example:
'Authorization':'BasicOTJjMGE0ZWItNDBiZS00MmE2LTlmNTAtNTk3Yzg2NjY2YjdiOlBiZGtPSmJ0WGpWVktMQ2hFY2ZybGZ2RFlYUlZ4Vw'
2. Content Type-application/x-www-form-urlencoded
Example:
'Content-Type':'application/x-www-form-urlencoded'
Request Body: The following parameters must be included in the body of the request.
- grant_type - Contains the value 'client_credentials'.
- scope - The desired authorization roles should be added to this parameter. The roles are separated by a space. The roles must also be configured with the OpenID Client. Also, the organization ID must be added to this parameter.
Example orgId:
'scope':'Basic orgId:7e6bb160-91d9-4093-bc50-9699d446e774′
Example orgCode:
'scope':'Basic orgCode:organization code′
Terms of Use
Access tokens generated via the OpenID Connect method have a certain lifetime. This lifetime of the access token can be configured in the OpenID Client on ANVA Hub. If a token is still valid, then the intention (fair use) is to reuse this token on subsequent requests to the api's of ANVA Hub (such as the XML module), until the moment when the access token is no longer valid. From this moment, of course, a new access token can be requested again via the OpenID Connect method. So it is not desirable to first request a new access token for every request to an api on ANVA Hub.
Learn more
For more information on the use and composition of requests and responses, please see the OpenID Connect specifications here
