Connect identity providers using OIDC/OAuth 2.0

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

If your client application handles the authentication directly with the external identity provider, some of the connection settings are not needed. The steps below guide you on this.

You can choose whether users are also provisioned from the identity provider to 10Duke Enterprise, or if 10Duke Enterprise only uses the received data to identify the user in the system.

To find out if the user already has a user account, 10Duke Enterprise checks first with the user ID provided by the identity provider, and if no match is found, then with the email address.

Note: This user ID is the external identity provider’s ID for the user. This external ID is different from the user ID in the 10Duke Enterprise user account, and not visible in SysAdmin.

Before you start

  • When 10Duke Enterprise connects directly to the identity provider, first define 10Duke Enterprise as a client at the identity provider’s end.

  • When defining the connection in SysAdmin, you need the OIDC Discovery document published by the identity provider. You can typically find it in the identity provider’s documentation or user interface. The document contains information needed for connecting to the identity provider, such as the issuer URL, the OAuth 2.0 endpoint locations, and the supported scopes.

    You also typically need some of the client details that you defined in the identity provider.

Step 1: Define the general details for a connection

  1. In the left sidebar, go to IDENTITY > Federation.

  2. Go to the OIDC Identity Providers tab and select Actions > Create. A dialog with tabs opens.

  3. Define the name and issuer URL for the identity provider:

    • Title: Define a name for the identity provider.

    • Identity Provider Name Id: Define the OIDC issuer URL of the identity provider.

      Make sure this matches the value in the iss field in the ID tokens created by the identity provider and the issuer field defined in the identity provider’s OIDC discovery document.

  4. Enable Identity Provider is globally trusted if you want to allow the identity provider to authenticate users with any email address, even if a user with a matching email address already exists in 10Duke Enterprise.

    Only enable this if the identity provider is trusted to only allow legitimate user email addresses, for example, if the identity provider is managed by the vendor (your organization).

    If you disable this, use Assigned Email Domains to define the email domains that are authenticated with this identity provider.

  5. Enable Mark primary email validated if you want the authenticated users email addresses to be marked as verified in their 10Duke Enterprise user account.

  6. In Assigned Email Domains (optional), define the email domains that are delegated to the identity provider. If a user’s email address belongs to one of these email domains, they’re always sent to this identity provider for authentication.

    To add an email domain, click Add, enter the domain. To delete an email domain, click the trash can icon next to it.

    If you don’t define email domains, a login option for this identity provider is displayed for all users, and they can choose to log in with this provider instead of with an email address. For example, with a social login provider such as Google, the login option is typically made available to all users, and the provider is defined as globally trusted.

Step 2: Define the client details for 10Duke Enterprise

  1. Go to the Client details tab.

  2. Enter the 10Duke Enterprise credentials for authenticating itself to the identity provider:

    • Client key: Enter the client ID (OAuth client_id).

    • Client secret: Enter the client secret.

  3. Define the login and logout callback URLs. These are not needed if the client application authenticates users directly with the identity provider.

    • Client login callback URL: Define the login callback URL (redirect URI) where the identity provider sends the authorization code after a successful authentication. 10Duke Enterprise uses the authorization code to request the access token from the identity provider.

      Use the URL https://<your 10Duke Enterprise instance>/user/oauth20/cb.

    • Client logout callback URL (optional): Define the URL that 10Duke Enterprise redirects to after a successful logout request.

      Use the URL https://<your 10Duke Enterprise instance>/user/oidc/idp-logout.

  4. In Claim source type, select where 10Duke Enterprise reads the user details (OIDC claims) from:

    • default: Both the ID token and UserInfo response received from the identity provider.

    • idtoken: The ID token.

    • userinfo: The UserInfo response.

    • accesstoken: The access token response.

    This setting is not needed when the client app authenticates users directly with the identity provider. Set the value to default.

  5. In Assertion consumption mode, select whether users are provisioned from the identity provider to 10Duke Enterprise:

    • read only: 10Duke Enterprise user accounts are not created or updated based on the identity provider’s user data.

      Note: If you use this value, users must be created in 10Duke Enterprise in advance or authentication with this identity provider will fail.

    • default or create/replace: Provision users from the identity provider to 10Duke Enterprise.

      If an existing user account is found for the authenticated user, the user account is updated. If no matching user account is found, 10Duke Enterprise creates a new one.

  6. In OAuth - OpenId Connect Scopes (optional), define the scopes used in the OIDC request that 10Duke Enterprise sends to the identity provider, separated with spaces. The identity provider must return claims requested by these scopes.

    Always include at least the scopes openid, profile, and email.

    This is not needed if the client application authenticates users directly with the identity provider.

  7. In Token Signature Public Key (optional), define the identity provider’s public key for verifying the signatures of ID tokens that the client application passes from the identity provider to 10Duke Enterprise.

    This is only needed when the client application authenticates users directly with the identity provider and connects to 10Duke Enterprise using the JWT bearer token authorization grant flow.

    The value can be either a public key in Privacy Enhanced Mail (PEM) format (typically available in the identity provider’s user interface) or the jwks_uri value in the identity provider’s OIDC Discovery document.

Step 3: Define the identity provider’s API endpoints

The identity provider API endpoints are not needed if the client application authenticates users directly with the identity provider.

  1. Go to the Identity Provider Details tab.

  2. In Authorization token URL, define the identity provider’s authorization endpoint URL where 10Duke Enterprise sends the user to be authenticated.

  3. In Access token URL, define the identity provider’s token endpoint URL from where 10Duke Enterprise requests the access token.

  4. In OpenID Connect userinfo URL (optional), define the identity provider’s endpoint URL where 10Duke Enterprise sends the UserInfo request.

    Define this URL if you set Claim source type to either default or userinfo (see above).

  5. In Single Sign-out trigger URL (optional), define the URL for redirecting to the identity provider’s logout endpoint for starting the process for single logout (SLO).

  6. When you’re ready with the settings on all the tabs, click Save to create the identity provider connection.

Select the new connection in the table: on the General tab that opens below, the Id field shows the unique ID of the identity provider connection. This identity provider ID must be included in the request path when calling some of the 10Duke API endpoints.

Step 4: Create user detail mappings

If needed, create the mappings for handling user details.

A mapping defines the following:

  • The source data. This can be either a user field received from the identity provider or a value defined in 10Duke Enterprise.

    You can use the latter, for example, to specify user groups that the authenticated users must be added to.

  • The user account field in 10Duke Enterprise that the source data is updated to.

What mappings are needed?

  • If the identity provider uses standard OIDC field names (claims), you don’t need to create mappings for the user fields received from the identity provider.

  • If non-standard fields are used:

    • Create mappings for the user ID and email address fields, which are needed for matching with existing user accounts.

      The user ID mapping is also needed if you plan to set up other integrations to the external system that acts as the identity provider.

    • If you enabled user provisioning in Assertion consumption mode, create the mappings for all the user account fields that need to be defined.

  • If you want to add the authenticated users to an organization’s user groups, create mappings for the organization ID and the user group’s type.

    As source data, either define values in 10Duke Enterprise in order to add all users to the same organization’s user group, or define user fields received from the identity provider if the information is received from there per user.

Example mappings

  • @provider/oid - @internal/uid

    This mapping takes the (identity provider’s) user ID for the user from the oid field and matches it with an external user ID field in the 10Duke Enterprise user account.

  • @provider/emailId - @internal/email

    This mapping takes the user’s email address from the emailId field and matches it with the email address field in the 10Duke Enterprise user account.

  • <organization ID> - @internal/organizationId

    This mapping specifies the organization ID for updating the user’s user groups. You can find the ID in the organization’s details.

  • <user group’s type> - @internal/organizationGroup

    This mapping specifies the user group’s type for updating the user’s user groups. You can find the type in the user group’s details.

Define the mappings

To create a mapping:

  1. Select the identity provider connection in the table. The settings open below.

  2. Go to the Response attributes section.

  3. Click Add. A new field pair is added at the end of the section.

  4. In the first field, define the source data.

    To define a field received from the identity provider, use the format @provider/<field name>.

  5. In the second field, select the user account field in 10Duke Enterprise.

    See more information on the details in user accounts.

  6. Click the save icon to save the mapping.

To delete a mapping, click the trash can icon next to it.

Step 5: Define how users’ groups and roles are updated

If you enabled user provisioning in Assertion consumption mode and defined the user field mappings in the previous step, by default those fields are updated in the user’s account in 10Duke Enterprise every time they log in.

If needed, for the user group and role fields (@internal/organizationGroup and @internal/organizationRole), you can change the information to be updated only on the user’s first login.

To do this, define a second mapping for both fields in the Response attributes section.

Example: These two mappings would take the user group from the identity provider’s group field and set it for the user only when they first log in:

@provider/group - @internal/organizationGroup

@updateMode/Create - @internal/organizationGroup

The same applies if the source data is a value defined in 10Duke Enterprise instead of an identity provider field.

Next steps

If you later make changes to the connection, the changes take effect immediately.

On this page