info@10duke.com

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 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:

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.

  • state is optional and 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:

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

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: {BASE_URL}
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
}

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.

Next steps

After a successful authentication, your client application can:

On this page