Connect identity providers using SAML

In 10Duke SysAdmin, you can connect external identity providers to 10Duke Enterprise using Security Assertion Markup Language (SAML).

In SAML terms, 10Duke Enterprise is the Service Provider (SP), and authentication uses the Web Browser SSO Profile (SP-initiated).

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

First define 10Duke Enterprise as a client at the identity provider’s end.

10Duke Enterprise’s SAML Service Provider metadata document contains information needed when defining the connection. You can find it at https://<your 10Duke Enterprise instance>/user/saml20/sp-metadata.
When defining the connection in SysAdmin, you need the SAML Identity Provider metadata 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 entity ID and the identity provider’s single sign-on service URL.

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

In SysAdmin in the left sidebar, go to IDENTITY > External identity providers.
Go to the SAML 2.0 identity providers tab and select Actions > Create. A dialog with tabs opens.
In Title, define a name for the identity provider.
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.
Enable Mark primary email validated if you want the authenticated users’ email addresses to be marked as verified in their 10Duke Enterprise user account.
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

Go to the Client details tab.
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.

You can ignore the other settings on the Client details tab.

Step 3: Define the identity provider’s details

Go to the Identity provider details tab.
In Identity provider ID, define the unique identifier (entity ID) of the identity provider.
Define the API endpoints of the identity provider.
- In IdP login URL, define the identity provider’s single sign-on service URL where 10Duke Enterprise sends the user to be authenticated.
- In Single sign-out trigger URL (optional), define the single logout service URL for redirecting to the identity provider’s logout endpoint for starting the process for single logout (SLO).

You can ignore the other settings on the Identity provider details tab.

Step 4: Create user detail mappings

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.

The identity provider’s Subject NameID claim is mapped by default to the external user ID field in the 10Duke Enterprise user account, @internal/uid.
Create a mapping for the email address field. For the source data, either use the emailaddress claim from the predefined options if it matches the claim returned by the identity provider, or enter the correct claim in the field.

Example mapping:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress - @internal/email: This mapping takes the user’s email address from the specified emailaddress claim (SAML assertion value) and matches it with the email address field in the 10Duke Enterprise user account.

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

Create mappings for all the user account fields that need to be defined.

At least the user’s first name and last name are needed for displaying users in Sysadmin. For the source data, either use the givenname, surname, and name (display name) claims from the predefined options if they match the claims returned by the identity provider, or enter the correct claim in the field.

Example mappings:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname - @internal/givenName

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname - @internal/surname

These mappings take the user’s first and last name from the specified claims and update them to the 10Duke Enterprise user account.
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 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:

Go to the Response attributes tab.
Click Add. A new field pair is added at the end of the section.
In the first field, define the source data.
In the second field, select the user account field in 10Duke Enterprise.

To delete a mapping, click Remove 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 specified identity provider’s field, and set it for the user only when they first log in:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/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

Step 6: Create the connection

When you’re ready with your settings, click Save to create the identity provider connection.

Next steps

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