Connect client applications using OIDC
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|
10Duke Authentication API endpoints:
|Item||URL (relative, prepend the environment base URL)|
|Device verification URI||
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 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 always authenticated, and your client application receives an access token for API authorization.
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.
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)
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.
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.
|Application type||Authentication variants|
|Desktop, mobile||Authorization code grant with PKCE (recommended)
|Web, client-server||Authorization code grant|
|Device with a limited user interface||Device authorization grant|