Authentication Concepts
Overview¶
DLL uses OAuth 2.0 with OpenID Connect to allow your applications to connect to DLL's APIs safely:
- OAuth 2.0 is the industry-standard protocol for Authorization.
- OpenID Connect extends OAuth 2.0 protocol by adding Authorization and Identity capabilities.
Terminology¶
DLL's API documentation follows the official OAuth 2.0 and OpenID Connect specifications to describe the various actors involved in the authentication and authorization process:
Term | Description |
---|---|
Client Application | The application that accesses DLL's APIs on behalf of the Resource Owner with the Resource Owner’s authorization or consent. |
Resource Owner | The Resource Owner provides the Client Application consent to access DLL's APIs on the Resource Owner’s behalf. |
Authorization Server | A server issuing Access Tokens to the Client Application after successfully authenticating the Resource Owner and obtaining authorization or consent. For example, the API Gateway Authorization Server. |
Resource Server | A server hosting the protected resources, which is capable of accepting and responding to protected resource requests using Access Tokens. For example, the API Gateway and API Manager collectively known as the API Gateway Resource Server. |
Scope | When a Client Application request access to the Resource Owner’s data, the Scope controls the level of access. Scopes on incoming requests to the Resource Server will be validated against the scopes registered in the API Gateway. |
Supported Authorization Flows¶
DLL supports the Client Credentials Grant Type allowing your application to make authenticated API calls without end-user consent.
Client Credentials Flow¶
Overview¶
The Client Credentials Grant Type should only be used by confidential Client Applications. When the Client Application requests access to a protected resource, the application must use its unique Client Credentials. You can find your credentials on the Applications page This Grant Type is suitable when Client Applications need access to protected resources not specific to an end-user. It is described in the OAuth 2.0 Authorization Framework standard (RFC 6749).
The Client Credentials Flow is the following:
sequenceDiagram
Client App->>+Authorization Server: Submits Client Credentials
Authorization Server->>+Authorization Server: Validates the credentials
Authorization Server->>+Client App: Sends back the Access Token without a Refresh Token
Client App->>+Resource Server: Request access to the protected resource with the Access Token
Resource Server->>+Resource Server: Validates the Access Token
Resource Server->>+Client App: Returns the protected resource
- The Client Application sends its Client Credentials to the Authorization Server.
- The Authorization Server validates the Client Credentials.
- After a successful validation, the Authorization Server sends back the Access Token to the Client Application without a Refresh Token.
- The Client Application sends an access request to the Resource Server along with the Access Token to access protected resources.
- The Resource Server validates the Access Token.
- After a successful validation, the Resource Server sends back the requested protected resources to the Client Application.
Requesting an Access Token¶
-
Use the following endpoint to send the Access Token request to the Authorization Server:
Method URL POST https://login.microsoftonline.com/mscb2cparautprd.onmicrosoft.com/oauth2/v2.0/token
-
Use the following parameters in the request. All parameters are required:
Parameter Description grant_type
The grant_type
is always:client_credentidals
client_id
You receive your Client ID during the application registration process in the DLL Developer Hub. You can find the your Client ID on the Applications page. client_secret
You receive your Client Secret during the application registration process in the DLL Developer Hub. You can find the your Client Secret on the Applications page. scope
Specifies the level of access requested by the Client Application. You can find the correct Scope ...
Replace [YOUR_CLIENT_ID]
and [YOUR_CLIENT_SECRET]
with your valid credentials, and [SCOPE]
with ...
POST /token HTTP/1.1
Host: https://login.microsoftonline.com/mscb2cparautprd.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&scope=[SCOPE]
RESPONSE
Note
The response shows how long the Access Token remains valid. If it expires, generate a new one by following the steps in the Requesting an Access Token flow again.
Warning
Store the generated Access Token securely on the client server/database. Keep in mind our Security Guidelines.
Next steps¶
- Now that you have a valid Access Token, you can start interacting with the APIs.
- Read about the Access Token management for the Client Credentials flow.
Access Token Management for the Client Credentials Flow¶
Overview¶
Since the Client in the Client Credentials Flow is typically a secure web server, it is not recommended to generate a new Access Token for every API request. Instead, for optimal efficiency, Clients should securely store the generated Access Tokens and reuse them until they expire.
Example Token Management Flow¶
- Request an Access Token, then store it securely on the client server or in the client database. You can find best practices in the Securing API Calls and Credentials chapter.
- Before using the stored Access Token in an API call, first check if it is still valid.
- If the stored Access Token is valid, you can proceed with your request.
- If the stored Access Token is expired or will expire very soon, generate a new Access Token.
- Since the Identity Provider can revoke an Access Token at any time, the Application Client should be robust enough to handle situations where an API request using a stored Access Token is rejected (e.g., a
401 Unauthorized error
). In such scenarios, the Client should request a new Access Token.