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 SysAdmin 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 and update 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 field in 10Duke Enterprise that the source data is updated to.

What mappings are needed?

At minimum, the external identity provider must send the user ID and email address of the user being authenticated, as they are needed for matching with existing user accounts in 10Duke Enterprise.

  • No mappings are needed for this if the identity provider uses the following standard OIDC field names (claims): sub, name, given_name, family_name, profile, picture, email, email_verified, gender, locale.

  • However, if the identity provider uses non-standard fields, create mappings for the user ID and email address fields.

    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.

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.

Additional mappings may be needed when user provisioning and updates are enabled with the Assertion consumption mode setting.

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

    If non-standard fields are used, create mappings for all the 10Duke Enterprise user account fields that must be set based on the received fields.

    At least the user’s first name and last name are needed for displaying users in Sysadmin.

  • If you also want to connect the authenticated users to an organization:

    • Create a mapping for the organization ID of the organization.

    • Create a mapping for the user group where to add the users. The source data can either point to a 10Duke Enterprise group ID or group type (such as employees) to add all users to the same group, or point to a field received from the identity provider if the group is received from there per user.

    • Create a mapping for the organization role to assign to the users, if needed. The source data can either point to a 10Duke Enterprise role ID or designator (such as orgadmin) to assign the same role to all users, or point to a field received from the identity provider if the role is received from there per user.

    Example mappings:

    cce56388-2c7f-4dd7-8007-b7c3fbd47901 - @internal/organizationId: This mapping specifies the organization ID. You can find the ID in the organization’s details.

    employees - @internal/organizationGroup: This mapping adds all users to the user group of type employees. You can find the group type in the user group’s details.

So, when user provisioning and updates are enabled, a user is created in 10Duke Enterprise based on the mappings when they’re authenticated for the first time, and their information is also updated at every authentication. In practice, an update replaces all the user’s current details, groups, and roles according to the mappings.

Note that if you only define the organization ID mapping but no user group and organization role mappings, the user’s user groups and organization roles will be cleared every time they’re authenticated. If needed, define additional mappings to control when (or if) the groups and roles are updated for the user.

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 and updates with the Assertion consumption mode setting, and you defined organization, user group, and organization role mappings in Response attributes, there might be some use cases where you don’t want users’ groups and roles to be updated every time they’re authenticated with the identity provider.

You can control this by defining an additional updateMode mapping. You can either limit updates to happen only the first time the user is authenticated, or prevent updates completely.

As an example of the first option, 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 second option of preventing updates completely could be used, for example, in a use case where the organization and user group mappings are needed for adding users to a user group, but users’ organization roles are being maintained on the 10Duke Enterprise side and shouldn’t be touched by the identity provider integration. If you just left out the organization role mapping altogether, a user’s assigned organization roles would be cleared at every authentication.

This example case requires the following updateMode mapping to prevent any changes to the user’s organization roles at authentication. The first type of mapping for pointing to the source data is not needed in this case.

@updateMode/None - @internal/organizationRole

Next steps

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

On this page