Connect client applications with alternative flows

While the authorization code grant or authorization code grant with PKCE flows are suitable for most cases, 10Duke Enterprise provides more options if these flows cannot fulfill the requirements of your client application.

See more information on the available flows and how to choose the correct one for your case.

JWT bearer token authorization grant flow

Use the JSON Web Token (JWT) bearer token authorization grant flow when you’re connecting a client application that authenticates users directly with an external identity provider.

The client application sends an ID token received from the external provider to 10Duke Enterprise, and 10Duke Enterprise grants an access token (and a new ID token) to the client application.

See also information on the request rate limit.

Before you start

• For 10Duke Enterprise to trust the authentication by the external identity provider, define the connection to the identity provider in 10Duke SysAdmin.

  By default, 10Duke Enterprise requires that the ID token from the external identity provider contains an aud value that matches the base URL of your 10Duke Enterprise deployment. This may require some configuration at the identity provider’s end. If needed, contact the 10Duke Integration Support team.

• Define an OIDC connection for your client application in SysAdmin.

  This includes defining the client ID (OAuth client_id) for your client application and the authentication flow used.

Step 1: Initiate authentication flow

Send a request to the 10Duke Enterprise access token endpoint.

An example request (line breaks added for display purposes):

POST /user/oauth20/token
   Content-Type: application/x-www-form-urlencoded

   assertion=ID_TOKEN_VALUE
   &grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
   &scope=openid profile
   &client_id=79w1-6s41-4s7x-8e96-76u986gs1

Set the content header to Content-Type: application/x-www-form-urlencoded.

In the form data (the request body), use grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, and provide the ID token in JWT format in assertion and the client ID in client_id.

In scope, provide the requested OAuth scopes. This must contain at least openid.

Step 2: Handle response

A successful call should return a response like this:

{
   "access_token": "ACCESS_TOKEN_VALUE",
   "scope":"openid profile",
   "id_token": "ID_TOKEN_VALUE",
   "token_type": "Bearer",
   "expires_in": 3600,
   "issued_at":1675702153
}

Your client application can use access_token to authorize 10Duke API requests and id_token granted by 10Duke Enterprise to read user details. By default, a refresh token is not provided with this flow.

The response fields may vary depending on the 10Duke Enterprise release. Make sure your client application is able to handle the response if new fields are added. The response can also contain additional fields depending on possible customizations.

Next steps

After a successful authentication, your client application can:

• Read the ID token or request more information about the user

• Use the access token to authorize API requests

Client credentials grant flow

When your client application is acting on its own behalf and there’s no user involved, use the client credentials grant flow to authenticate the client application and get authorization to access the 10Duke Enterprise APIs.

Before you start

Define an OAuth connection for your client application in 10Duke SysAdmin.

This includes defining the client ID (OAuth client_id) and client secret for your client application and the authentication flow used.

With this flow, API authorization is not based on a user’s permissions, so the SysAdmin OAuth connection must also specify the permissions needed by the client to access the APIs.

This prerequisite is not needed if the client is created by some other means (for example, a device client is created by invitation).

Step 1: Initiate authentication flow

Send a request to the 10Duke Enterprise access token endpoint.

An example request (line breaks added for display purposes):

POST /user/oauth20/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=client_credentials
   &client_id=todo_api_key
   &client_secret=todo_api_secret

Set the content header to Content-Type: application/x-www-form-urlencoded.

In the form data (the request body), use grant_type=client_credentials, and provide actual values in client_id and client_secret.

The scope parameter is not needed: the currently supported OAuth scopes are not relevant for the client credentials grant flow, which doesn’t involve a user.

Step 2: Handle response

A successful call should return a response like this:

{
   "access_token": "ACCESS_TOKEN_VALUE",
   "refresh_token": "REFRESH_TOKEN_VALUE",
   "scope":"",
   "token_type": "Bearer",
   "expires_in": 3600,
   "issued_at":1675702153
   "refresh_token_expires_in":86400
}

Your client application can use access_token to authorize 10Duke API requests and refresh_token (if granted and included in the response) for requesting new access tokens. refresh_token_expires_in contains the seconds until the OAuth session expires, after which the client application can no longer refresh the access token.

The response fields may vary depending on the 10Duke Enterprise release. Make sure your client application is able to handle the response if new fields are added. The response can also contain additional fields depending on possible customizations.

Next steps

After a successful authentication, your client application can:

• Use the access token to authorize API requests

• Use the refresh token to request a new access token

Password grant flow (legacy)

The password grant flow (also known as resource owner password credentials grant) is a legacy flow that is superseded by the authorization code grant with PKCE flow.

These instructions are provided for the benefit of old client applications that still use the password grant flow.

The other OIDC flows use 10Duke Enterprise or an external identity provider for end user login. With the password grant flow, your client application prompts the end user for a username and password and sends a request with these credentials to the access token endpoint /user/oauth20/token of the 10Duke Authentication API.

The password grant flow allows API authorization in a similar manner as the other flows. However, because of the different authentication process, only simple username and password authentication is supported, and features such as two-factor authentication (2FA), social login, and federation are not supported.

If your 10Duke Enterprise configuration defines that 2FA is required also with the password grant flow, authentication using this flow fails for users who have 2FA enabled (or if 2FA is globally enforced). Contact the 10Duke Integration Support team for a configuration change if needed.

See also information on the request rate limit.

Before you start

Define an OIDC connection for your client application in 10Duke SysAdmin.

This includes defining the client ID (OAuth client_id) and client secret for your client application and the authentication flow used.

Step 1: Initiate authentication flow

Send a request to the 10Duke Enterprise access token endpoint.

An example request (line breaks added for display purposes):

POST /user/oauth20/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=password
   &username=alfred
   &password=secret
   &scope=openid profile
   &client_id=todo_api_key
   &client_secret=todo_api_secret

Set the content header to Content-Type: application/x-www-form-urlencoded.

In the form data (the request body), use grant_type=password, and provide actual values in username, password, client_id, and client_secret.

In scope, provide the requested OAuth scopes. This must contain at least openid.

Step 2: Handle response

A successful call should return a response like this:

{
   "access_token": "ACCESS_TOKEN_VALUE",
   "refresh_token": "REFRESH_TOKEN_VALUE",
   "scope":"openid profile",
   "id_token": "ID_TOKEN_VALUE",
   "token_type": "Bearer",
   "expires_in": 3600,
   "issued_at":1675702153
   "refresh_token_expires_in":86400
}

Your client application can use access_token to authorize 10Duke API requests, refresh_token (if granted and included in the response) for requesting new access tokens, and id_token to read user details. refresh_token_expires_in contains the seconds until the OAuth session expires, after which the client application can no longer refresh the access token.

The response fields may vary depending on the 10Duke Enterprise release. Make sure your client application is able to handle the response if new fields are added. The response can also contain additional fields depending on possible customizations.

Next steps

After a successful authentication, your client application can:

• Read the ID token or request more information about the user

• Use the access token to authorize API requests

• Use the refresh token to request a new access token

Implicit flow (legacy)

The implicit flow is a legacy flow that is superseded by the authorization code grant with PKCE flow.

These instructions are provided for the benefit of old client applications that still use the implicit flow.

Before you start

• Define an OIDC connection for your client application in 10Duke SysAdmin.

  This includes defining the client ID (OAuth client_id) for your client application, the authentication flow used, and the redirect URI for receiving the access token.

• The following steps assume that a desktop application or a browser interacts with the user and 10Duke Enterprise directly without its own server side involved at all.

Step 1: Initiate authentication flow

From the client application, send the user agent (browser) to the 10Duke Authentication API’s authentication/authorization endpoint.

An example URL where the browser is sent (line breaks added for display purposes):

<BASE_URL>/user/oauth20/authz
   ?response_type=token+id_token
   &scope=profile+email
   &client_id=todo_api_key
   &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
   &state=xyz
   &nonce=todo_nonce

When the end user has completed the login in the browser and been successfully authenticated, the browser is redirected back to the client application’s redirect URI.

Step 2: Handle redirect request

Handle the redirect request in the client application, and extract the access token that was sent with the request in the access_token query parameter.

The login callback information is in the URL parameter form in the URL fragment, after the # character in the URL (line breaks added for display purposes):

https://client.example.com/cb
   #access_token=bNXrLNRSR-hWHRa109MUcYagUGM
   &token_type=Bearer
   &expires_in=31536000&state=xyz
   &id_token=e2F0X2hhc2g6IHlLTE1IRlhrNEo3TzBpMS1WejM1Wnc9PSxzdWI6IGRhMjFhOWZiLTU5NmItNGI3MS1hODZmLWM0Y2YyN2RlN2ZlZSxhdWQ6IHRvZG9fYXBpX2tleSxpc3M6IGh0dHBzOi8ve0lEUF9IT1NUfTo0NDMsZXhwOiAxNTE1ODQ4MTcwLGdpdmVuX25hbWU6IFRlc3QsaWF0OiAxNTE1NzYxNzcwLG5vbmNlOiBhZGQxMmQxYy1jNzZiLTQwYzYtODhlZS1iYzQwMDNkNTQ1NGYsZmFtaWx5X25hbWU6IFVzZXJ9

Your client application can use access_token to authorize 10Duke API requests and id_token to read user details. By default, a refresh token is not provided with this flow.

The response fields may vary depending on the 10Duke Enterprise release. Make sure your client application is able to handle the response if new fields are added. The response can also contain additional fields depending on possible customizations.

Next steps

After a successful authentication, your client application can:

• Read the ID token or request more information about the user

• Use the access token to authorize API requests

Request rate limit

Your 10Duke Enterprise configuration defines a rate limit for the password grant and JWT bearer token authorization grant flows. This limits how many times a single user is allowed to perform authentication (log in) within a specified time period.

By default, three authentication requests within five minutes are allowed. If there’s a fourth request within the five minutes, authentication fails and 10Duke Enterprise returns an HTTP error code 429 Too Many Requests.

10Duke Enterprise also starts to slow down the response rate (up to 55 seconds) and sets a 5-minute cooldown period for the user, communicated in the error response. If another request comes before the cooldown period is over, a new cooldown period starts and the delay for returning a response increases. If the cooldown period has already ended, the request counting against the rate limit is reset.

If you want changes to the default configuration, contact the 10Duke Integration Support team.