Connect to external identity providers
With 10Duke Enterprise support for the OpenID Connect (OIDC) protocol and the Security Assertion Markup Language (SAML) 2.0 protocol, it’s easy to set up user authentication with identity providers in your ecosystem.
When an external identity provider is used for user authentication, 10Duke Enterprise is configured to trust the identity provider and communicate with it as needed. A common example is authenticating users using Microsoft Azure Active Directory (Azure AD), which is used in many corporate environments.
10Duke Enterprise can delegate authentication to an external identity provider so that 10Duke Enterprise passes on authentication requests from client applications to the identity provider. Client applications only communicate with 10Duke Enterprise, and setting up the external identity provider doesn’t require changes in the client applications. This means you can flexibly implement scenarios such as customer identity federation, social login, and single sign-on (SSO) with your (the vendor’s) own identity provider.
When using OIDC, 10Duke Enterprise supports the authorization code grant flow. When using SAML, 10Duke Enterprise supports the SAML Web Browser SSO Profile.
A client application can also communicate directly with an external identity provider and authenticate users. In this case, 10Duke Enterprise doesn’t communicate directly with the external identity provider.
-
10Duke Enterprise is configured to trust the identity provider, and the client application sends an ID token received from the external provider to 10Duke Enterprise. 10Duke Enterprise is able to rely on the user authentication described by the ID token and grant an access token to the client application to authorize API access.
-
In this scenario, the client application uses the JWT bearer token authorization grant flow to connect to 10Duke Enterprise.
In addition to user authentication, you can provision the authenticated users from the identity provider to 10Duke Enterprise and keep the user data in sync.
API endpoints
OIDC/OAuth API endpoints
| Item | URL (relative, prepend the environment base URL) |
|---|---|
| External provider redirect | /user/oauth20/cb |
| Single logout (SLO) | /user/oidc/idp-logout |
SAML API endpoints
| Item | URL (relative, prepend the environment base URL) |
|---|---|
| Assertion Consumer Service | /user/saml20/cb |
| Single logout (SLO) | /user/saml20/idp-signout |
SAML Service Provider metadata document
When connecting through SAML, 10Duke Enterprise’s SAML Service Provider metadata document contains information needed when defining the connection at the identity provider’s end.
Find the document for 10Duke Enterprise at:
https://<your 10Duke Enterprise instance>/user/saml20/sp-metadata
Configurations needed
-
When 10Duke Enterprise connects directly to the external identity provider, the identity provider must be configured to recognize 10Duke Enterprise as a client and pass the appropriate claims when called. The steps needed depend on the identity provider, but the process is typically straightforward.
See our configuration guides for the main identity providers that our customers use with 10Duke Enterprise:
If you need advice on how to connect to some other identity provider, contact the 10Duke Integration Support team.
-
10Duke Enterprise must be configured to recognize the external identity provider.
Define the connection to the identity provider in 10Duke SysAdmin. This includes defining the claims, response attributes, and so on, and enabling the provisioning of users if needed.
Troubleshooting
You may come across the following error situations.
Missing required user attributes
By default, 10Duke Enterprise requires that the external identity provider returns at least the ID, email address, first name, and last name of the authenticated user. If any of these are missing, 10Duke Enterprise gives an error message naming the missing data.
Either configure the external identity provider to return the missing data, or if this is not possible, contact the 10Duke Integration Support team.
The user already exists
When an end user is authenticated for the first time with an external identity provider, 10Duke Enterprise checks if a user with the authenticated email address already exists.
If an existing user is found, 10Duke Enterprise checks if the identity provider’s connection settings in SysAdmin allow logging in the existing user using the identity provider. If logging in is not allowed, 10Duke Enterprise gives an error message describing a user data conflict.
In the identity provider’s connection settings, you must either define the email domain as an assigned email domain or define that the identity provider is globally trusted.
Authentication fails due to no valid client secret
When using OIDC to connect to an external identity provider, the connection requires 10Duke Enterprise to have a valid client secret from the identity provider, or the end user’s authentication fails.
If end users are no longer able to log in, check if the identity provider connection defined in SysAdmin contains a valid client secret.
If client secrets are rotated or set to expire at the identity provider’s end, it’s important that you always keep the client secret in the SysAdmin connection up-to-date with the changes.