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. |
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).
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
.
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.
-
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 asunspecified
orbasic
. -
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>
-
Add an attribute statement to your SAML configuration with the name
domino-system-roles
, and choosebasic
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
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
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.