10Duke Enterprise release 3 documentation is no longer being updated

Connect client applications using OIDC/OAuth 2.0

When connecting your client application to 10Duke Enterprise, using OpenID Connect (OIDC) provides you with both authentication of users and authorization of API requests with OAuth 2.0 access tokens.

Here are some key OIDC terms and how they map to 10Duke Enterprise terms:

OIDC term 10Duke Enterprise term
Authorization server 10Duke Enterprise
User agent The browser used by the end user for logging in, either a standard browser or an in-app embedded browser
Client The application (desktop, mobile, web) that needs to call the 10Duke APIs
Resource owner The end user

API endpoints

10Duke Authentication API endpoints:

Item URL (relative, prepend the environment base URL)
Authorization /user/oauth20/authz
Access token /user/oauth20/token
User information /user/info
Single logout /user/oauth20/signout
Device authorization /user/oauth20/device-authz
Device verification URI /user/device

OIDC discovery document

10Duke Enterprise provides an OIDC Discovery document, which contains information that you need when implementing the connection to 10Duke Enterprise in your client application, including the public key used for verifying the signatures of ID tokens issued by 10Duke Enterprise.

The document is available at https://<your 10Duke Enterprise instance>/user/.well-known/openid-configuration.

Authentication process with OIDC and OAuth 2.0

OIDC is an authentication layer built on top of OAuth 2.0. When using OIDC to authenticate an end user, the process always enables API authorization by OAuth 2.0 for the client application.

OIDC/OAuth 2.0 provides a selection of authentication flows to choose from. 10Duke Enterprise makes multiple flows available so that you can choose the flow best suited for your client application.

There are differences between the flows, but ultimately the user is authenticated, and your client application receives an access token for API authorization. With the client credentials grant flow that doesn’t involve a user, you can grant permissions to the client application itself when needed by API operations.

In addition to an access token, the client application may be granted a refresh token. When the access token expires, the client application can request a new access token using the refresh token. This doesn’t require any user interaction.

The detailed steps depend on the authentication flow you choose. See more information on the available flows below.

Authentication flows

You can choose from the following OIDC flows:

  • Authorization code grant (recommended for web, client-server)

    You can use this when a web server interacts with the user through a browser. Because your client application has a server-side component, it’s capable of holding a client secret that this flow requires.

  • Authorization code grant with PKCE (recommended for desktop, mobile and stand-alone web)

    With the Proof Key for Code Exchange (PKCE) extension, you can use the authorization code grant flow with public clients such as mobile, desktop, and stand-alone JavaScript browser applications.

  • Device authorization grant

    You can use this when your client application is not capable of using a web browser for user authentication. With this flow, the user interaction is done in a web browser on another device.

  • Client credentials grant

    You can use this when your client application doesn’t involve any user, for example, with integrations or device-based licensing.

    Because there’s no user when using this flow, the client application cannot receive OIDC ID tokens or request user information, but it can use OAuth access tokens and refresh tokens in the same way as with the other flows.

  • Password grant (also known as resource owner password credentials grant)

    You can use this in cases where your client application needs to provide a native user interface for the username and password prompt instead of using a browser-based user interface.

    When using this option, you can only implement basic username and password authentication, and features such as multi-factor authentication (MFA), social login, and federation are not available.

  • JWT bearer token authorization grant

    You can use this when your client application implements user authentication by communicating directly with an external identity provider that supports OIDC.

    With this option, 10Duke Enterprise doesn’t participate in the user authentication. After authenticating the user with the external identity provider, your client application receives an OIDC ID token from the identity provider. The client application can use this ID token for 10Duke API authorization.

Which flow to choose?

See below which authentication variants are the most appropriate for your application type, and click to see instructions.

Application type Authentication variants
Desktop, mobile Authorization code grant with PKCE (recommended)
Password grant
Web, client-server Authorization code grant
Stand-alone web page (JavaScript) Authorization code grant with PKCE
Device with a limited user interface Device authorization grant
Device client or integrated system with no user Client credentials grant