Domino Cloud SSO integration

Domino Cloud can be integrated into SAML2 SSO IDPs with minimal required configuration. Note that for security reasons, this integration comes disabled by default.

Note	This document provides guidance for configuring Domino Cloud instances, which come with a pre-built SSO provider. If you want to manually configure a non-cloud instance, see Single sign-on (SSO) configuration for more details.

Cluster endpoint

The redirect URI for your cluster will have the following pattern:

https://{your-cluster-name}.domino.tech/auth/realms/DominoRealm/broker/saml/endpoint

This URL will be both the recipient and destination of the Single Sign-On process, as well as the Entity ID (audience URI).

SAML descriptor

You can download the SAML descriptor metadata from the following URL:

https://{your-cluster-name}.domino.tech/auth/realms/DominoRealm/broker/saml/endpoint/descriptor

This will include expected attributes, as well as the configured nameID format.

Required attributes

NameID, username and email

Users are uniquely identified by their email, and their username will be automatically derived from it. The resulting username is obtained by keeping the email username (without the domain) and normalizing them.

If the provided NameID is in the email format, this is done automatically. No extra attribute is required for the email.

<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">john.smith@acme.org</saml2:NameID>

Typically, however, the SAML endpoint returns a NameID which is a GUID that is not suitable for a username. In this case, an explicit email attribute is used instead. This attribute must be called email.

Data attributes

If you don’t want your users to be required to provide their personal details on the first login, add these attributes to prepopulate them.

firstName
lastName

Integrating roles with Domino Cloud

If you also want to use the third-party provider for authorization, then set the domino-system-roles attribute to include the desired roles. You will then need to request Domino Support to enable role synchronization for your cluster.

Once this is enabled, all roles will need to be explicitly provided. This includes previously defaulting roles such as Practitioner.

Available roles

Available roles for Domino Cloud users are:

Practitioner
CloudAdmin
Librarian
ProjectManager

Note	If roles are integrated with the IDP, changes done through Domino’s admin panel will not be reflected and will be overwritten the next time the user logs in. You will need to make changes to the provided `domino-system-roles` attribute sent instead.

Multiple roles support

The domino-system-roles attribute supports the multi-valued attribute format. Provide each role in a separate AttributeValue in the authentication claim. CSV is currently not supported.

Okta-specific configurations

If you are using Okta as your SSO provider, you can either:

Use Okta groups to control the attributes being sent.
Use attributes for every user logging in through SSO using Okta expressions.

Using Okta groups

Create a group in your Okta environment for every Domino role you want users linked to. The group names must exactly match Domino’s role names.
Create a Group Attribute Statement called domino-system-roles, and set the format as unspecified or basic.
Add a filter so that only Domino-related groups are sent. You can use a regex filter like Practitioner|CloudAdmin|Librarian|ProjectManager.

At login time, Okta will provide a list of all groups the user is currently assigned to (that match the provided filter) under the domino-system-roles attribute.

<saml2:Attribute Name="domino-system-roles"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Practitioner
    </saml2:AttributeValue>
    <saml2:AttributeValue
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">CloudAdmin
    </saml2:AttributeValue>
</saml2:Attribute>

Using Okta expressions

Add an attribute statement to your SAML configuration with the name domino-system-roles, and choose basic as the format.
Provide the Okta expression that will evaluate to the appropriate roles array at login time.

For fixed roles (if you want all users logging in through SSO to have the same roles), you can use a simple expression such as the inline array {"CloudAdmin", "Practitioner"}. For more complex use cases, see the Okta expression reference: Okta Expression Language#Array Functions. Note that the result of the expression needs to be an array, not a CSV string.

Azure-specific configurations

If you are using Azure as your SSO provider:

Make sure the created application is an Enterprise application.
Make sure that SAML is selected as the SSO authentication mechanism.
Update the SSO attribute claims to provide the required data attributes. Microsft ships some claims out of the box, but the names they are generated with will not match with the attribute names expected by Domino. Also make sure to remove the namespaces for the provided attribute claims, as they won’t match otherwise.
Update the entity ID so it matches with the SSO URL. You can do this by downloading the SAML descriptor metadata, and re-uploading it to your application configuration.

The expected entity ID will be similar to:

https://{your-cluster-name}.domino.tech/auth/realms/DominoRealm

The expected Reply URL will be similar to:

https://{your-cluster-name.domino.tech/auth/realms/DominoRealm/broker/saml/endpoint

Logout URL will be similar to:

https://{your-cluster-name}.domino.tech/auth/realms/DominoRealm/broker/saml/endpoint

Using Azure groups

Note	You will need an Azure subscription capable of assigning user groups to Enterprise Applications in order to do this. This is only required for using Azure as the authorization provider, and is not required if you will only use Azure for authentication purposes.

Open Enterprise Applications, select the application in the list, select Single Sign-On configuration, and then select User Attributes & Claims.
Add a new Group Claim.
For the group type emitted in the token, select Groups assigned to the application.
For the Source Attribute, select Cloud-only group display names.
In advanced settings of the group claim, check "Customize the name of the Group Claim". Use domino-system-roles as the claim name, and no Namespace.
In the Groups tab, assign one group to the application per Domino role you wish to map to. Group names need to match available roles for Domino Cloud.

For more details, see Microsoft Entra - Emit cloud-only group display name in token

Reaching back to Domino Support

Once you have configured the SSO provider accordingly, the following needs to be provided to Domino Support to complete enabling the integration:

The Single Sign-On Service URL to be used for authentication. For Okta, this is usually in the format of https://{customer-okta-domain}.okta.com/app/{okta-app-name}/{s0m3rand0m1d}/sso/saml
The certificate for signature validation.
Whether roles should be integrated with the SSO provider or not.
A custom name to be used on the cluster login page for the button, if desired. Defaults to saml for a "Continue with saml" button.

IDP-initiated flows

Domino Cloud currently does not support initiating the authentication flow from the SSO provider. Attempting to do so will result in errors similar to this:

We are sorry...

Invalid request

SSO can only be initiated from the Domino Cloud cluster’s login page, through the "Continue with {my sso}" button.