Connect web server applications (authorization code grant flow)

The authorization code grant flow is widely used and the OIDC/OAuth 2.0 flow that we recommend when connecting web server applications.

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

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, the authentication flow used, and the redirect URI for receiving the OAuth authorization code.

  • The following steps assume that your application has access to a browser to show the login page to the end user.

    If you’re connecting an application that doesn’t already support user login, your application must be modified to do so. See the available 10Duke client libraries.

Step 1: Initiate authentication flow

From the client application, send the user agent (browser) to the 10Duke Authentication API’s authentication/authorization endpoint at https://<your environment base URL>/user/oauth20/authz.

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

https://customer.10duke.net/user/oauth20/authz
   ?response_type=code
   &client_id=79w1-6s41-4s7x-8e96-76u986gs1
   &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback
   &scope=openid%20profile%20email
   &state=AnyStateFromClient

Use the base URL of your 10Duke Enterprise environment, and provide actual values in client_id and redirect_uri.

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

Optional parameters:

  • If the user is not logged in yet, by default the login page is opened for them. With flow=register, you can request to open the registration page instead.

  • Provide the user’s email address in login_hint, which enables 10Duke Enterprise to automatically populate the email address field so the user doesn’t have to fill it in again.

  • state can be anything that the client application wants to get back after login.

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: Extract authorization code

Handle the redirect request in the client application, and extract the authorization code that was sent with the request in the code query parameter.

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

https://client.example.com/callback
   ?code=SplxlOBeZQQYbYS6WxSbIA
   &state=AnyStateFromClient

Step 3: Get access token

To exchange the authorization code for an access token, send an HTTPS POST request to the 10Duke Enterprise access token endpoint at https://<your environment base URL>/user/oauth20/token.

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

POST /user/oauth20/token HTTP/1.1
   Host: customer.10duke.net
   Content-Type: application/x-www-form-urlencoded

   grant_type=authorization_code
   &code=SplxlOBeZQQYbYS6WxSbIA
   &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback
   &client_id=todo_client_key
   &client_secret=verysecret

Use the base URL of your 10Duke Enterprise environment, and set the content header to Content-Type: application/x-www-form-urlencoded.

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

A successful call should return a response like this:

{
   "access_token": "ACCESS_TOKEN_VALUE",
   "remember":false,
   "refresh_token": "REFRESH_TOKEN_VALUE",
   "scope":"openid profile"
   "id_token": "ID_TOKEN_VALUE",
   "token_type": "Bearer",
   "expires_in": 3600,
   "issued_at":1675702153
   "refreshable_until":1675662553
}

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. refreshable_until contains the expiry time of the OAuth session, 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:

On this page