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:

API endpoints

10Duke Authentication API endpoints:

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 required 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.

A client application that uses a client secret is called a confidential client, and other clients are public. All flows return an OAuth access token to the client, but by default, a refresh token is only returned to confidential clients. It’s possible to return a refresh token to any client if needed. You define separately for each client connection in 10Duke SysAdmin whether refresh tokens are granted to the client application.

Which flow to choose?

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