Connect client applications using OIDC/OAuth 2.0

In 10Duke SysAdmin, you can connect client applications to 10Duke Enterprise using OpenID Connect (OIDC)/OAuth 2.0.

Step 1: Define the general details for a client application

1. In the left sidebar, go to IDENTITY > Client applications.

2. Go to the OAuth 2.0 clients tab and select Actions > Create. A dialog opens.

3. In Title, define a name of the client application.

4. Enter the client application’s credentials for authenticating itself to 10Duke Enterprise:

   • OAuth client id: Enter the OAuth client ID (client_id) of the client application.

   • Client secret (optional): Enter the client secret. This is not needed if the client application is public.

Step 2: Define the login and logout callback URLs

1. In Login callback URL (optional), define the login callback URL (redirect URI) where your client application receives and processes the response from the authorization server (10Duke Enterprise). This is often also the URL to which users are redirected when their authentication is complete.

   For example, when the OAuth 2.0 authorization code grant flow is used, the response from the authorization server includes an authorization code, which is a temporary code that the client application exchanges for an access token.

   You can define multiple redirect URLs if needed, for example, if your client application uses multiple domain names. You can add more redirect URLs after you have completed these steps and saved the connection.

   Note: Sensitive information is sent to the redirect URI, so it’s important that only appropriate redirect locations are allowed. Whitelist the redirect URIs to avoid redirecting the user to arbitrary locations.

   The redirect URI can be any URI, but note the following:

   • Desktop applications with an embedded browser typically use custom URIs such as myapp:signon.

   • Desktop applications that use the operating system’s default browser typically use HTTP and not HTTPS, for example, http://localhost:*/oidc-cb.

   • Web applications should use HTTPS.

   • The default matching for redirect URIs is a case-sensitive exact match. We recommend that you use the default match, but 10Duke Enterprise also supports wildcard (*) and regex matching.

2. In Logout callback URL (optional), define the logout callback URL for this client application if you’re using single logout (SLO) to handle logouts for multiple client applications.

   If the user is signed in to this client application and SLO is started from another application, 10Duke Enterprise calls this URL to log the user out from this client application as well.

Step 3: Define when access tokens expire

In Session attachment, select when access tokens (and user sessions) in the client application expire:

• Attached: The access token expires either when the maximum access token validity time has been reached or when the end user logs out (the session ends), whichever comes first.

  An access token is specific to a client application, and there are no interdependencies between client applications. However, if two “attached” clients receive a token in the same login session, logging out invalidates the access tokens of both applications.

  This option is usually used with web clients.

• Detached: The access token expires when the maximum access token validity time has been reached.

  Use this option when the validity of the access token must not be tied to the user session in a browser, nor be invalidated by a logout.

  This option is usually used with desktop and mobile clients. A client that uses a built-in browser doesn’t share login sessions with other clients, and it can fully control user sessions without involving the built-in browser. When a client uses the operating system’s default browser and the user logs out in the browser, in most cases the user wouldn’t expect to be logged out from the client application.

• Detached when user chose remember me: The Detached option is used if the end user selected “Remember me” when logging in, otherwise the Attached option is used.

  This option can be used when the client application gives the user control over what happens when the user logs out in the browser that they used for logging in. For example, a desktop application that uses the operating system’s default browser could invalidate access tokens on browser logout if the user didn’t select the “remember me” option, and keep the tokens alive if the user selected that option.

Step 4: Select the OAuth 2.0 flow

In Allowed OAuth 2.0 flow, select the OAuth 2.0 flow used with the client application.

Note: For the authentication of your licensed client applications, we recommend that you use the authorization code grant flow with Proof Key for Code Exchange (PKCE).

• None: Use this if you need to disable the client application’s access to 10Duke Enterprise.

• Authorization Code Grant (without PKCE) (see more in RFC 6749)

• Authorization Code Grant with PKCE (recommended, see more in RFC 6749 and RFC 7636)

• Authorization Code Grant (with/without PKCE)

• Resource Owner Password Grant (see more in RFC 6749)

• Client Credentials Grant (see more in RFC 6749)

• Implicit Grant (see more in RFC 6749)

• Device Grant (see more in RFC 8628)

• JWT Authorization Grant (see more in RFC 7523)

• Allow any: Allow the client application to use any OAuth 2.0 flow. This option is intended mainly for development purposes and should be avoided in production.

Step 5: Define if refresh tokens are used

1. In Grant refresh token, define if refresh tokens are used.

   • Enable the toggle to allow the client application to request a new access token when the current one expires, and refresh the user session without any interaction needed from the user.

     The client application can refresh the user session using an OAuth refresh token, which the 10Duke Enterprise sends to the client application together with the access token.

   • If you disable the toggle, the client application must always start a new authentication process when the access token expires.

   Note: The flow selected in Allowed OAuth 2.0 flow may affect the use of refresh tokens: for security reasons, the refresh token may not be granted when using some of the flows.

   For example, if you’re using the legacy implicit flow, the authorization server should not issue refresh tokens. This flow is often implemented in single-page applications (SPA) that run on the frontend layer of a system architecture, and there’s no easy way to keep a refresh token secure.

2. Click Save to create the connection to the client application.

Step 6: Grant permissions

On the Permissions tab, you can grant permissions (or “elevated privileges”) to trusted client applications to access resources in 10Duke Enterprise.

With most of the OAuth 2.0 flows, API authorization is based on the authenticated user’s roles and permissions, and there’s usually no need to grant permissions to the client application itself.

As an exception, using the client credentials grant flow requires defining permissions here, because there’s no user involved.

Select the new connection in the table and define the permissions on the Permissions tab.

Contact the 10Duke Integration Support team before using this feature.

Next steps

• If needed, add more redirect URLs for the connection in Login callback URL: enter a URL in the empty field and click Add. To remove a URL, click Remove next to the field.

• Implement the OIDC connection in the client application.

If you later make changes to the client application connection in SysAdmin, the changes take effect immediately.

You can disconnect a client application when it no longer needs to be connected to or delegate authentication to 10Duke Enterprise. To disconnect, delete the connection on the OAuth 2.0 clients tab. After disconnecting a licensed software application, end users can no longer use the application to consume licenses.