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

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

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

  3. In Title, define a name for the identity provider.

  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. In Client identifier, enter the unique identifier (entity ID) of 10Duke Enterprise for authenticating itself to the identity provider.

    This is the entityID value from the SAML Service Provider metadata document of your 10Duke Enterprise deployment, located at https://<your 10Duke Enterprise instance>/user/saml20/sp-metadata.

  3. 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.

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

Step 3: Define the identity provider’s details

  1. Go to the Identity Provider Details tab.

  2. In Identity Provider Identifier, define the unique identifier (entity ID) of the identity provider.

  3. Define the API endpoints of the identity provider.

    • In IdP Login URL (optional), 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 user account field in 10Duke Enterprise that the source data is updated to.

What mappings are needed?

  • By default, the identity provider’s Subject NameID field is mapped by default to the external user ID in 10Duke Enterprise, @internal/uid.

  • Create mappings for the email (@internal/email), first name (@internal/givenName), and last name (@internal/surname) fields in 10Duke Enterprise.

    These are needed for syncing user data to 10Duke Enterprise and for displaying users in Sysadmin. There’s a predefined list of IdP claims covering emailaddress, name, givenname, and surname that you can select from. You can use these values if they match the claims returned by the identity provider, or you can enter the correct claims in the text field.

  • 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

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress - @internal/email

    This mapping takes the user’s email address from the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress field (SAML assertion value) 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. Go to the Response attributes tab.

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

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

  4. 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 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 field that contains the user group, 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 same applies if the source data is a value defined in 10Duke Enterprise instead of an identity provider field.

Step 6: Create the connection

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

(You can ignore the settings on the last two tabs, Signatures and Encryption.)

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.

Next steps

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

On this page