Using OAuth 2.0 to Access VRP APIs
VRP APIs use the OAuth 2.0 protocol for authentication and authorization.
Public API supports the following both authentication methods:
- Using Harmonized Identity Management as Identity provider
- Using authentication in Azure AD.
This page gives an overview of the OAuth 2.0 authorization scenarios that DN supports.
Basic steps
All applications follow a basic pattern when accessing a VRP API using OAuth 2.0. At a high level, you follow steps:
1. Obtain OAuth 2.0 credentials from the HIDM or Azure AD
Contact the respective environment devOps team responsible for creating the tenant and sharing the credentials. The process of providing credentials is automated and the CI/CD pipeline will trigger the credentials (client ID and client secret) via email to the selected user.
2. Obtain an access token from the Azure AD or HIDM
Before your application can access private data using a VRP API, it must obtain an access token that grants access to that API.
Use the following endpoint to get the token from the Azure AD:
Note: For HIDM, the token URL varies depending on the environment.
Request Parameters:
| Parameter | Type | Value |
|---|---|---|
grant_type | Required | client_credentials |
client_id | Required | Your Client ID |
client_secret | Required | Your Client Secret |
scope | Required | The scope of the API you are accessing. Due to security reasons please contact the respective environment devOps team for details. Static value for all calls. Different scope for prod and non-prod environment. |
Note: scope value for HIDM is: DN_FULL_API |
Sample Request for Azure AD
Note: For HIDM, the token URL varies depending on the environment.
Response Parameters:
A success response is a JSON OAuth 2.0 response with the following parameters.
| Parameter | Description |
|---|---|
token_type | Indicates the token type value. The only type that the Microsoft identity platform supports is Bearer. |
expires_in | The length of time, in seconds, that the access token is valid. |
access_token | The requested access token. The calling service can use this token to authenticate to the receiving service. |
Sample Response:
3. Send the access token to an API
After an application has acquired an access token, it sends the token to a VRP API in an HTTP Authorization request header
4. Refresh the access token, if necessary
Access tokens have limited lifetimes - 15 minutes (due to security reason). If your application needs access to a VRP API beyond the lifetime of a single access token, it can obtain a new access token. Refresh tokens are not supported.
- It is mandatory to refresh an access token before the expiration time (15 minutes).
- To refresh token use the same URL as in Step 2. The response body is the same as for Step 2.
Note: Save access tokens in secure long-term storage and continue to use them as long as they remain valid.
Client Apps token generated via HIDM services
- There is no limit on the number of users who can use the client application credentials at a time.
- Once token is generated, then it will be used till expiration is hit. (Example: In case there are two tokens generated back to back both are valid).
Client Apps token generated via Azure AD
- There is no limit on the number of users that can use the client application at the same time.