Keycloak is a user authentication service that runs in a pod on your Domino cluster. Domino uses Keycloak to view, create, and manage groups of users. See the official Keycloak documentation for details.
You can access the Keycloak instance on any Domino cluster at https://<your-domino-domain>/auth/
.
You must sign in to the Keycloak admin console at least once to initialize the authentication service.
Enable user registration from the Keycloak console so users can sign up to join your fresh Domino install.
Keycloak offers several user authentication methods:
To access your Keycloak instance, visit https://<your-domino-domain>/auth/
.
You must sign in to the Keycloak admin console at least once to initialize the authentication service.
Before your first sign in, you must retrieve the admin password.
-
Retrieve the administrator password from the
keycloak-http
Kubernetes secret:kubectl -n <domino-platform-namespace> get secret keycloak-http -o yaml
The following is a sample response:
apiVersion: v1 data: password: <encrypted-password> kind: Secret metadata: creationTimestamp: 2019-09-09T21:23:15Z labels: app.kubernetes.io/instance: keycloak app.kubernetes.io/managed-by: Tiller app.kubernetes.io/name: keycloak helm.sh/chart: keycloak-4.14.1-0.10.2 name: keycloak-http namespace: domino resourceVersion: "6746" selfLink: /api/v1/namespaces/domino/secrets/keycloak-http uid: 09009f96-d348-11e9-9ea1-0aa417381fd6 type: Opaque
-
Decrypt the password from the response:
echo '<encrypted-password>' | base64 --decode
-
Use this password to sign in to
https://<your-domino-domain>/auth/
with the usernamekeycloak
.
Domino automatically configures Keycloak with a realm named DominoRealm
, to create and manage new users.
When you review or change settings for Domino authentication, ensure that you have DominoRealm
selected.
You can enable or disable Domino user registration from the Keycloak admin console. Make sure to enable user registration, so users can join your fresh Domino install.
-
In the Keycloak sidebar menu, click Realm Settings.
-
Click the Login tab, and toggle User registration to On or Off.
-
Click Save.
The simplest option for authentication to Domino is to use local usernames and passwords. When you choose local authentication, Keycloak stores all user data in Postgres.
User management
Your first sign in as administrator automatically configures Keycloak with realms. A realm is the Keycloak equivalent of a tenant. It’s used to manage groups of users. The default Keycloak admin account is in the Master realm. Master realm accounts can view, create, or update accounts in other realms. Domino also automatically configures a realm called DominoRealm. DominoRealm accounts are non-admins and have ordinary user privileges.
In the Keycloak sidebar, from the menu, click DominoRealm.
DominoRealm
Click Master.
See the official Keycloak documentation for details about realms and the Keycloak admin console.
Set permissions to activate or deactivate users
To activate or deactivate users from an admin account, you must assign the admin account the manage-users
role.
If the admin account doesn’t have that role, it’ll receive a 403 error if you sign in to it and try to update a user’s status.
-
From the Keycloak sidebar, go to Manage > Users.
-
Select the admin account you want to assign the
manage-users
role to.
-
Click the Role Mappings tab.
-
For Client Roles, in Available Roles, click manage-users.
-
If you’re already signed in to Domino, sign out and then sign in again.
To activate or deactivate user accounts, see Manage Users.
When you choose federated authentication, Keycloak connects to the provider and caches user information.
Add a provider
-
In the Keycloak console, go to the User Federation menu.
-
Click Add provider… > LDAP.
See the official Keycloak documentation for full details about user storage federation.
If you migrate from an older Domino version, use your
ldap.conf
from the Domino frontend to see what inputs to use for the provider settings.Some of these inputs include:
ldap.conf name Keycloak user federation setting name Search principal
Bind DN
Search base
Users DN
Search filter
Additional Filtering
You can synchronize Domino administrative user roles and organization membership with attributes in your SAML identity provider. Use this to externalize management of these roles and memberships to the identity provider.
-
Use an LDAP mapper to import user attributes to Keycloak.
-
Follow the steps in Synchronize SSO Group and Role related to Client Mappers to map from Keycloak to Domino.
Configure mappers
Review the LDAP mapper associated with your provider. You must make sure that there are LDAP mappers for the following attributes:
-
username
-
firstName
-
lastName
-
email
For more details, read the official Keycloak documentation about LDAP mappers.
When you choose SSO authentication, you can integrate Domino with a SAML 2.0 or OpenID Connect (OIDC) identity provider. SSO delegates authentication to the identity provider, so users don’t have to create a username and password specific to Domino.
Configure single sign-on
Domino can integrate with a SAML 2.0 or OIDC identity provider for Single Sign-On (SSO) with the steps outlined below.
Create a new Domino SAML service provider (SP)
-
From the Keycloak sidebar menu, click Identity Provider.
-
Select SAML v2.0.
Configure alias and determine redirect URI
-
Provide an Alias for the newly created provider. The alias field is a unique name for the provider in Keycloak. It’s part of the Redirect URI used by the provider service to route SAML responses and redirect users after their account is authenticated.
The redirect URI is case-sensitive. It takes the following form:
`https://<deployment_domain>/auth/realms/DominoRealm/broker/<alias>/endpoint`
For example, if the deployment’s domain is domino.acme.org and the provider’s alias is domino-credentials, the redirect URL will be:
https://domino.acme.org/auth/realms/DominoRealm/broker/domino-credentials/endpoint
Note
Create a SAML endpoint in your upstream identity provider
-
Create a SAML application in the identity provider that will be integrated with Domino. To create the application you need the Redirect URI from the previous step.
The specific procedure to create the SAML endpoint depends on your identity provider. Domino can integrate through SAML with Okta, Azure AD, Ping, and any other provider that implements SAML v2.0.
After the SAML endpoint has been created and configured, export an XML metadata file to complete the configuration of the provider in Keycloak.
The following are important properties of the SAML endpoint you will create in the provider. After you create and configure the SAML endpoint, you must export an XML metadata file to complete the configuration of the provider in Keycloak.
NameID
controls the format of the <saml2:NameID>
element in the SAML response.
This is used to derive the SSO username in Domino.
- Option 1
-
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Users are uniquely identified by their email, and their username will be automatically derived from it.
Example:
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
john.smith@acme.org
</saml2:NameID>
- Option 2
-
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
The SAML endpoint must respond with a string that can be used as a username without any modification.
Example:
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
jsmith
</saml2:NameID>
- Option 3
-
urn:oasis:names:tc:SAML:1.1:nameid-format:persistent
Typically, the SAML endpoint returns a NameID that is a GUID which is not suitable for a username. If the endpoint must use this format, then an additional attribute that contains the username must be returned.
To automatically populate the user’s Domino profile, the SAML response must contain the following attributes. Without these attributes, the user will be prompted to complete the required elements of their user profile.
The required attributes are:
-
firstName
-
lastName
-
email
-
username
(ifnameId
is not an email or does not represent the username). -
destination
No specific attribute names are expected as these can be mapped in Keycloak.
Import metadata and complete configuration in Keycloak
Use the metadata file from the previous step to complete configuration of the provider in Keycloak.
-
Go to the end of the identity provider configuration page.
Note -
Choose the file to import, then click Import.
Most of the provider settings are configured automatically.
-
Save the configuration.
After you’ve completed the initial configuration, confirm the following settings are configured correctly.
Trust Email - Yes
Ensures that emails supplied from IdP are trusted even if Email Verification is enabled for DominoRealm.
Sync Mode - force
Ensures that user data is updated during every login with the identity provider, allowing Keycloak to pick up changes from the upstream identity provider.
NameID Policy Format
This was configured on import, but verify that it matches the option configured on the external endpoint.
-
Want Assertions Signed -
Yes
-
Validate Signature -
Yes
The respective signature field must already be populated based on the metadata you imported when you set up SSO authentication.
Additional options such as Assertion Encryption and Request Signing are supported, but require additional configuration coordination between Keycloak and the endpoint in your identity provider.
After you save the provider in Keycloak, an Export tab opens with XML metadata for the provider. Use this to automatically configure the external endpoint.
The metadata will also be available at:
https://<deployment domain>/auth/realms/DominoRealm/broker/<alias>/endpoint/descriptor
Configure attribute mappers
To make the experience of new users signing in for the first time seamless, and not require them to complete their profile on initial login, you must pass several SAML attributes in the SAML response, and ensure these are correctly mapped to Domino user attributes.
If the attributes are not properly mapped, upon first login users will be prompted to complete the empty fields in their profile.
To map these values from the SAML assertion attributes to the user profile model, you must configure an Attribute Importer mapper from the Mappers tab.
- First Name mapper
-
-
Name:
First Name
-
Sync Mode Override:
inherit
-
Mapper Type:
Attribute Importer
-
Attribute Name: Name attribute for the
<saml2:Attribute>
element that contains the value to be mapped toFirst Name
. -
Friendly Name:
FriendlyName
attribute (optionally available) for the<saml2:Attribute>
element that contains the value to be mapped toFirst Name
. -
User Attribute Name:
firstName
-
- Last Name mapper
-
-
Name:
Last Name
-
Sync Mode Override:
inherit
-
Mapper Type:
Attribute Importer
-
Attribute Name: Name attribute for element that contains the value for
Last Name
. -
Friendly Name:
FriendlyName
attribute for the<saml2:Attribute>
element that contains the value forLast Name
. -
User Attribute Name:
lastName
-
- Email mapper
-
-
Name:
Email
-
Sync Mode Override:
inherit
-
Mapper Type:
Attribute Importer
-
Attribute Name: Name attribute for element that contains the value for
Email
-
Friendly Name:
FriendlyName
attribute for the<saml2:Attribute>
element that contains the value forEmail
. -
User Attribute Name:
email
-
The following example illustrates how to map First Name
from an assertion with the following payload:
<saml2:Attribute Name="customSAMLFirstName" FriendlyName="FriendlyFirstName">
<saml2:AttributeValue>John</saml2:AttributeValue>
</saml2:Attribute>
You can map this with:
Alternatively, you can map this with:
The mapper configuration for the username depends on how the external endpoint is configured with respect to NameID Policy options.
-
Option 1:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
-
Use
Email Prefix as UserName Importer
-
Example:
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"> john.smith@acme.org </saml2:NameID>
Map as shown:
-
-
Option 2:
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
-
No need to do an importer. The username will be mapped automatically to the
NameID
value -
Example:
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"> jsmith </saml2:NameID>
-
-
Option 3:
urn:oasis:names:tc:SAML:1.1:nameid-format:persistent
-
Use
Username Template Importer
with Template of${ATTRIBUTE.<attribute Name>}
or${ATTRIBUTE.<attribute FriendlyName>}
-
Example:
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"> jsmith </saml2:NameID> <saml2:Attribute Name="customUserName"> <saml2:AttributeValue>jsmith</saml2:AttributeValue> </saml2:Attribute>
Map as follows:
-
See Mapping Claims and Assertions for additional information on attribute mapping.
When you use the Email Prefix as Username Importer mapper as illustrated previously (Option 1), the generated user name will be the email prefix, stripped of all characters except alphanumeric and underscores. Special characters will be converted to underscores, characters with diacritics will be converted to their ascii base.
If a username from an external system is already present, the same transformation rules will be applied to it.
For example, a username $jöhn.smîth#home$
or an email address $jöhn.smîth#home$@somehost.com
would both be mapped to the username john_smith_home
.
When you troubleshoot SAML attribute mapping, refer to a specification for the SAML response that your identity provider endpoint sends back to Keycloak after authentication.
A thorough specification will detail the NameID
policy format and attributes sent in the response.
If such a specification is not available, or the attribute mapping does not function as expected, you might have to examine a SAML response that is returned from a login attempt. One way to do this is to use the SAML-tracer extension available for Chrome and Firefox. This allows you to examine decoded SAML requests and responses to:
-
See the returned attributes (and whether any are missing).
-
Verify that the names or formats are as expected.
Domino First Broker Login authentication flow
To configure the recommended login authentication flow, click the Domino First Broker Login
flow:
See authentication flows for more information.
Restrict access for SSO users to Domino
Typically, when you configure the SAML endpoint that will provide SSO authentication for Domino, the provider administrator restricts the endpoint to a subset of users who are allowed to authenticate through it.
In rare cases, where limitations in the provider software don’t allow you to constrain the set of users who can authenticate against the endpoint, the provider must pass an additional SAML attribute. This attribute specifies if a user is allowed to access Domino. The value of that attribute depends on a specific rule for each user. Usually, it is based on membership in a group in your identity provider.
Use the following as a last resort, if all identity provider restriction options are exhausted.
The Domino Keycloak instance must have keycloak.profile.feature.scripts
enabled.
An attribute must indicate whether a properly authenticated user can log in to Domino.
- AttributeName
-
-
Suggested: rolesForDomino
-
Can be anything as this is mapped.
-
- Multi-valued:
Yes
- Value
-
-
Contains one or more values that can be used to gate access. Typically, these values are roles or groups.
-
You must add an additional mapper to your provider configuration in Keycloak.
Use an Attribute Importer mapper type.
-
Name:
Allow in Domino
-
Mapper Type:
Attribute Importer
-
Attribute Name:
Name
attribute for the element that contains the flag. -
Friendly Name:
FriendlyName
attribute for the element that contains the groups for the user. -
User Attribute Name:
accessforDomino
Example:
<saml2:Attribute Name="rolesForDomino">
<saml2:AttributeValue>dave-users</saml2:AttributeValue>
<saml2:AttributeValue>it-users</saml2:AttributeValue>
</saml2:Attribute>
By default, Domino doesn’t provide a post login flow so you must add one.
-
Go to Authentication > Flows.
-
Click New:
-
Create a generic flow named Post Login Flow.
-
In the new flow, click Add execution.
-
Select
Script
. -
Go to Actions > Config.
-
Use the following script and modify the attribute value as needed.
/* * Template for JavaScript based authenticator's. * See org.keycloak.authentication.authenticators.browser.ScriptBasedAuthenticatorFactory */ // import enum for error lookup AuthenticationFlowError = Java.type("org.keycloak.authentication.AuthenticationFlowError"); /** * An example authenticate function. * * The following variables are available for convenience: * user - current user {@see org.keycloak.models.UserModel} * realm - current realm {@see org.keycloak.models.RealmModel} * session - current KeycloakSession {@see org.keycloak.models.KeycloakSession} * httpRequest - current HttpRequest {@see org.jboss.resteasy.spi.HttpRequest} * script - current script {@see org.keycloak.models.ScriptModel} * authenticationSession - current authentication session {@see org.keycloak.sessions.AuthenticationSessionModel} * LOG - current logger {@see org.jboss.logging.Logger} * * You one can extract current http request headers through: * httpRequest.getHttpHeaders().getHeaderString("Forwarded") * * @param context {@see org.keycloak.authentication.AuthenticationFlowContext} */ function authenticate(context) { //name of the attribute that needs to be 'true' to allow a user to authenticate in Domino var requiredAttrName = "accessForDomino"; var requiredAttrMustContain = "dave-users"; var errorMessageId = "userNotAssignedToDominoInIdp"; var errorPageTemplate = "error.ftl"; if (user === null) { context.success(); return; } LOG.info(script.name + " trace script auth for: " + user.username); var requiredAttrValues = user.getAttribute(requiredAttrName) LOG.info("User gated on attribute: " + requiredAttrName); LOG.info("Attribute values from SSO: " + requiredAttrValues) LOG.info("Attribute must contain: " + requiredAttrMustContain); if (requiredAttrValues === null || requiredAttrValues.size() === 0 || requiredAttrValues.contains(requiredAttrMustContain)) { //user is explicitly allowed in Domino LOG.info("User is allowed in Domino."); context.success(); return; } //user is not authorized to access Domino LOG.info("User is not allowed in Domino."); context.failure(AuthenticationFlowError.IDENTITY_PROVIDER_DISABLED, context.form().setError(errorMessageId, null).createForm(errorPageTemplate)); }
-
Make the execution required.
Customize the SSO button
-
In Keycloak, go to the default
domino-theme
. -
Update the Display text.
If Display text is blank or corresponds to the identity provider’s Alias, the button shows the default text, Continue with Single Sign On.
If any text other than the value of the Alias field is used, that value is used as the text on the button.
Test and troubleshoot
If you encounter errors from the Keycloak service when you attempt an SSO login, you can view the Keycloak request logs through kubectl
.
Run the following:
kubectl -n <domino-platform-namespace> logs keycloak-0
Session and token timeouts
Domino interacts with Keycloak through the OpenID Connect protocol, which uses two JWT tokens.
-
Access token gives its bearer access to the secured resource (can be used to authenticate requests).
-
Refresh token is not recognized by the secured resources, but it is used to request a fresh valid access token from the identity provider (Keycloak).
When the user authenticates with Keycloak and gets redirected to Domino, both tokens are saved in the Domino server-side session. Every time a request from the user’s browser is made to Domino, the server-side session is checked. If the access token is about to expire or has expired, Domino attempts a background call to Keycloak to request another access token. If this call is successful, the user’s request is served, otherwise the user is logged out. If the refresh token is expired, the user is logged out.
Keycloak has several timeouts that affect this behavior:
- Access Token Lifespan
-
This defines how long an access token is valid. Domino will not re-check the validity of the user’s authentication with Keycloak until this token expires. The default value is 5 minutes.
- SSO Session Max
-
This setting has no effect on the lifespan of any tokens, but it limits the maximum length of the user’s session with Keycloak. Even if the user refreshes their tokens and actively uses Domino, they will be logged out at the end of this period. The default value is 60 days.
- SSO Session Idle
-
This defines the maximum period of time in which the user’s session on Keycloak must be refreshed, otherwise it will be terminated. It defines the lifespan of the refresh token. This period must be longer than Access Token Lifespan, and not longer than SSO Session Max.
Important
See the Keycloak documentation for more information about timeouts.
Overview
If you enable SSO for Domino, you can configure Amazon Web Service (AWS) credential propagation. Use this to let Domino automatically assume temporary credentials for AWS roles that are based on roles assigned to users in the upstream identity provider.
See A New and Standardized Way to Manage Credentials in the AWS SDKs to learn more about how to use a credential file with the AWS SDK.
The following describes the overall workflow from user login to credential usage.
-
The Identity Provider Relying Party/Application validates the
Issuer
element in the AuthnRequest (SAML request) sent by Domino. -
Domino validates the Audience (Entity ID of the SP) in the SAML Response sent by the Identity Provider Relying Party/Application.
-
AWS AssumeRole validates that the
Issuer
of the SAML Response passed on from Domino matches theIssuer
of the Identity Provider Relying Party/Application. You can set up validations for other fields.
Enable credential propagation in Domino
-
To enable credential propagation, in the Admin application, go to Advanced > Central Config and set the following central configuration values.
-
Key:
com.cerebro.domino.auth.aws.sts.enabled
Value:
true
-
Key:
com.cerebro.domino.auth.aws.sts.region
Value: Short AWS region name where your Domino is deployed, such as
us-west-2
-
Key:
com.cerebro.domino.auth.aws.sts.defaultSessionDuration
Value: Default session duration, such as
1h
for 1 hourExample of a valid configuration:
-
-
To make the changes take effect, restart the services.
SAML provider configuration prerequisites
You must configure federation between your AWS account and your identity provider independently of Domino. See AWS Federated Authentication with Active Directory Federation Services (AD FS) for an example.
The SAML provider application must include the appropriate AWS federation attributes, based on the roles of each user.
Since Domino will refresh the user’s credentials during an active session, you must ensure that any AWS Identity and Access Management (IAM) role that you propagate to a user has assume-self
policy.
For example:
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "<ARN for the role>"
}
}
Expected SAML attributes
-
Attribute with Name
https://aws.amazon.com/SAML/Attributes/Role
-
Multi-valued:
Yes
-
Value format:
-
Comma-separated key-value pair of provider and role.
-
<provider arn>,<role arn>
-
arn:aws:iam::<acct #>:saml-provider/<provider name>,arn:aws:iam::<acct #>:role/<role name>
Note
-
-
-
-
Attribute with Name
https://aws.amazon.com/SAML/Attributes/RoleSessionName
-
Multi-valued:
No
-
Value:
-
String to be used as identifier for the temporary credentials.
-
Usually set to the email of the user.
-
-
-
Attribute with Name
https://aws.amazon.com/SAML/Attributes/SessionDuration
-
Multi-valued:
No
-
Value:
-
Duration in seconds of how long a user can stay logged in before the initial set of credentials for each of the roles is invalidated.
-
The duration must be smaller than the maximum allowable duration for each of the roles made available for a given user
-
-
To validate that you’ve established trust between AWS and the identity provider, sign in to Domino and check that the SAML response contains the expected SAML attributes. You can use the SAML-tracer extension available for Chrome and Firefox to examine SAML requests and responses to see that the appropriate attributes appear.
Example:
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/Role">
<saml2:AttributeValue xsi:type="xs:string">
arn:aws:iam::123456789012:saml-provider/acme-saml,arn:aws:iam::123456789012:role/role1
</saml2:AttributeValue>
<saml2:AttributeValue xsi:type="xs:string">
arn:aws:iam::123456789012:saml-provider/acme-saml,arn:aws:iam::123456789012:role/role2
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName">
<saml2:AttributeValue xsi:type="xs:string">
john.smith@acme.org
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/SessionDuration">
<saml2:AttributeValue xsi:type="xs:string">
900
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
Map AWS federation attributes
Go to the Mappers tab and configure an Attribute Importer mapper.
-
AWS Roles
-
Name: AWS Roles
-
Mapper Type:
Attribute Importer
-
Attribute Name:
https://aws.amazon.com/SAML/Attributes/Role
-
Friendly Name: <blank>
-
User Attribute Name:
aws-roles
-
-
AWS Role Session Name
-
Name: AWS Role Session Name
-
Mapper Type:
Attribute Importer
-
Attribute Name: `https://aws.amazon.com/SAML/Attributes/RoleSessionName
-
Friendly Name: <blank>
-
User Attribute Name:
aws-role-session-name
-
-
AWS Session Duration
-
Name: AWS Session Duration
-
Mapper Type:
Attribute Importer
-
Attribute Name:
https://aws.amazon.com/SAML/Attributes/SessionDuration
-
Friendly Name: <blank>
-
User Attribute Name:
aws-session-duration
-
Additional provider configuration
To give Domino access to users SAML assertions, enable the following settings from the identity provider:
-
Store Tokens: On
-
Store Tokens Readable: On
Domino-client configuration
The domino-play OpenID Connect (OIDC) client is pre-populated with client mappers, so that identity provider-mapped SAML information will flow into Domino.
-
In the DominoRealm, go to the Clients tab and click domino-play.
-
Click the Mappers tab for the domino-play client. The following are the default domino-play client mappers:
-
identity-provider-mapper
-
aws-roles-mapper
-
Client ID
-
domino-group-mapper
-
Client IP Address
-
Client Host
-
aws-session-duration-mapper
-
domino-user-groups-mapper
-
aws-role-session-name-mapper
-
domino-system-roles-mapper
-
-
Create a new mapper with type User Session Note and the following settings:
-
Name:
identity-provider-mapper
-
Mapper Type:
User Session Note
-
User Session Note:
identity_provider
-
Token Claim Name:
idpbroker
-
Claim JSON Type:
string
-
Add to ID token:
On
-
Add to access token:
On
-
-
To make the changes take effect, sign out of and sign back into Domino.
Usage
Once configured properly the first time, you must log out and log back into Domino.
To confirm that credentials are propagating correctly to users, start a workspace and check the environment variable
AWS_SHARED_CREDENTIALS_FILE
and that your credential file appears at /var/lib/domino/home/.aws/credentials
.
This should be sufficient for a user to connect to AWS resources without further configuration. Click here to see an example of connecting to s3.
Learn more about using a credential file with AWS SDK.
Confirm the configuration
To confirm that you have successfully set up AWS credential propagation, start a workspace and check the environment variable AWS_SHARED_CREDENTIALS_FILE
as well as the credential file, /var/lib/domino/home/.aws/credentials
.
To test your configuration outside Domino, perform an AssumeRoleWithSAML
call with the SAML token provided to Domino by your identity provider.
Example:
aws sts assume-role-with-saml \
--role-arn arn:aws:iam::521624712688:role/DataScientist-dev \
--principal-arn arn:aws:iam::521624712688:saml-provider/ADFS-DOMINO \
--saml-assertion "PHNhb.......VzcG9uc2U+"
SSO group and role synchronization
Domino can synchronize Domino administrative user roles and organization membership with attributes in your SAML identity provider. Use this to externalize management of these roles and memberships to the identity provider.
SAML Group to Organization synchronization
The SAML provider application connected to Domino must include group membership as a multi-valued attribute.
-
To enable this feature, you must update the Domino central configuration setting,
authentication.oidc.externalOrgsEnabled
totrue
, then restart Domino services.
Add an Attribute Importer mapper to the provider configuration in Keycloak.
-
Name: Domino Groups
-
Mapper Type:
Attribute Importer
-
Attribute Name: Name attribute for element that contains the groups for the user.
-
Friendly Name:
FriendlyName
attribute for element that contains the groups for the user. -
User Attribute Name:
domino-groups
.
Example:
<saml2:Attribute Name="UserGroups">
<saml2:AttributeValue>nyc-data-scientists</saml2:AttributeValue>
<saml2:AttributeValue>all-data-scientists</saml2:AttributeValue>
<saml2:AttributeValue>sensitive-claims-users</saml2:AttributeValue>
</saml2:Attribute>
When Domino is installed, it automatically creates the domino-group-mapper
client mapper.
-
To review the client mapper, go to Clients and click domino-play.
-
Click the Mappers tab. You can see the
domino-group-mapper
.
Role synchronization
In addition to group membership, you can also automatically assign Domino administrative and/or user roles to users based on attributes from your SAML identity provider.
The SAML identity provider application connected to Domino must include attributes that can be mapped to specific Domino roles.
To enable this feature you must set the Domino central configuration setting, authentication.oidc.externalRolesEnabled
to true
, then restart Domino services.
You must add an Attribute Importer mapper to the provider configuration in Keycloak.
-
Name: Domino System Roles
-
Mapper Type:
Attribute Importer
-
Attribute Name: Name attribute for element that contains the Domino system roles for the user.
-
Friendly Name:
FriendlyName
attribute for element that contains the groups for the user. -
User Attribute Name:
domino-system-roles
.
The domino-system-roles
client mapper is created at installation.
-
To review the client mapper, go to Clients and click domino-play.
-
Click the Mappers tab. You can see the
domino-system-roles
.
Summary of Domino SAML attribute requirements
This section covers the SAML attributes expected by Domino to enable different pieces of functionality.
SSO attributes
You must have the following attributes to establish single sign-on between Domino and your identity provider:
-
Username
-
NameID
(In Subject element) -
Preferred format:
urn:oasis:names:tc:SAML:1.1:nameid-format:email
-
-
First Name
-
Attribute name: Can be any name since Domino allows attribute mapping.
-
-
Last Name
-
Attribute name: Can be any name since Domino allows attribute mapping.
-
-
Email
-
Attribute name: Can be any name since Domino allows attribute mapping.
-
-
Destination
Example:
<saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:email">
john.smith@acme.org
</saml2:NameID>
...
</saml2:Subject>
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute Name="DominoEmail">
<saml2:AttributeValue xsi:type="xs:string">
john.smith@acme.org
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="DominoFirstName">
<saml2:AttributeValue xsi:type="xs:string">
John
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="DominoLastName">
<saml2:AttributeValue xsi:type="xs:string">
Smith
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
Credential propagation attributes
The following attributes are optional unless you use the credential propagation functionality of Domino:
-
AWS Roles
-
Attribute Name:
https://aws.amazon.com/SAML/Attributes/Role
-
Multi-valued: Yes
-
Value format:
-
Comma-separated key-value pair of provider and role.
-
<provider arn>,<role arn>
-
arn:aws:iam::<acct #>:saml-provider/<provider name>,arn:aws:iam::<acct #>:role/<role name>
Note
-
-
-
AWS Role Session Name
-
Attribute Name:
https://aws.amazon.com/SAML/Attributes/RoleSessionName
-
Multi-valued: No
-
Value:
-
String to be used as identifier for the temporary credentials assumed.
-
Typically the user’s email.
-
-
-
AWS Session Duration
-
Attribute Name:
https://aws.amazon.com/SAML/Attributes/SessionDuration
-
Multi-valued: No
-
Value:
-
Duration in seconds of how long the user can stay logged in before the credentials for each of the roles are invalidated.
-
The duration must be smaller than the maximum allowable duration for each of the roles made available for a given user.
-
-
Example:
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/Role">
<saml2:AttributeValue xsi:type="xs:string">
arn:aws:iam::123456789012:saml-provider/acme-saml,arn:aws:iam::123456789012:role/role1
</saml2:AttributeValue>
<saml2:AttributeValue xsi:type="xs:string">
arn:aws:iam::123456789012:saml-provider/acme-saml,arn:aws:iam::123456789012:role/role2
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName">
<saml2:AttributeValue xsi:type="xs:string">
john.smith@acme.org
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/SessionDuration">
<saml2:AttributeValue xsi:type="xs:string">
900
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
Group synchronization attributes
You must include the following attributes if you synchronize groups in Domino.
-
Domino Organizations
-
Name: Can be any name since Domino can map attributes.
-
Multi-valued: Yes
-
Values:
-
One or more of the groups the user belongs to in your centralized identity provider. For any groups specified here, the user will be automatically enrolled in a Domino organization with the same name.
-
-
Example:
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute Name="DominoOrganizations">
<saml2:AttributeValue>nyc-data-scientists</saml2:AttributeValue>
<saml2:AttributeValue>all-data-scientists</saml2:AttributeValue>
<saml2:AttributeValue>sensitive-claims-users</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
Administrative role synchronization attributes
You must include the following attributes if you sync administrative roles in Domino.
-
Domino System Roles
-
Name: Can be any name since Domino can map attributes.
-
Multi-valued: Yes
-
Values:
-
One or more values that are an exact, case-sensitive match to one of the Domino administrative roles.
-
Practitioner
-
SysAdmin
-
Librarian
-
ReadOnlySupportStaff
-
SupportStaff
-
ProjectManager
-
-
-
Example:
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute Name="DominoSystemRoles">
<saml2:AttributeValue xsi:type="xs:string">
SysAdmin
</saml2:AttributeValue>
<saml2:AttributeValue xsi:type="xs:string">
Librarian
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
To limit the number of sessions a user can run at once, configure a Keycloak authentication flow. The flow that you must configure depends on how you authenticate users:
-
Configure a browser flow if you use local or LDAP/AD authentication.
-
Configure a post-sign in client flow if you use SSO.
In addition, to limit concurrent sessions for API access, you must set up a Domino First Broker Login flow.
You can limit the number of active user sessions that a user can have open at one time. When a user reaches the user session limit, they must end their current user sessions before they begin a new session. You can stop user sessions from the Keycloak admin console, or users can sign out on their own.
Use Keycloak’s user management
Concurrent user sessions limits must be applied individually to each flow. If you have multiple clients or flows, you must add a concurrent user session limit for each one.
Browser flow for Local and LDAP/AD authentication
-
Copy the default browser flow (this default flow can’t be customized directly).
-
Click the copy of the default flow.
-
Click the <Flow Name> Forms row from XYZ.
-
From Actions, click Add Execution.
-
Click User Session Count Limiter if the limit should be applied to a single user. Click Realm Session Count Limiter if the limit should be applied to to all the users in a realm. A realm is the Keycloak version of a tenant.
-
Return to the flow page.
-
Set the execution you created to Required.
-
From the Actions menu, click Config.
-
Create a name for the execution and configure the authenticator.
-
Click Clients > domino-play.
-
In Authentication Flow Overrides, from Browser Flow, click your copied browser flow, and click Save.
First broker flow for API access
-
Copy the direct grant flow (this default flow can’t be customized directly).
-
Click the copy of the default flow.
-
Click Add Execution on the Actions menu.
-
Click User Session Count Limiter if the limit should be applied to a single user. Click Realm Session Count Limiter, if the limit should be applied to to a group of users.
-
Return to the flow page.
-
Set the execution you just created to Required and click Config from the Actions menu in the same line.
-
Create a name for the execution and configure the authenticator.
-
Click Clients > domino-play.
-
In Authentication Flow Overrides, from Direct Grant Flow, click your copied direct grant flow, and click Save.
SSO version
Unlike other kinds of flows, you can’t directly add a user session limit to a client authentication flow. However, you can still limit the number of user sessions if you add a flow that executes after the user signs in:
-
From the Keycloak sidebar, click Authentication.
-
Click New on the Flow Definition page.
-
Name the new flow, set the flow type to generic and click Save.
-
Click Add Execution on the Actions menu.
-
Click User Session Count Limiter if the limit should be applied to a single user. Click Realm Session Count Limiter if the limit should be applied to a group of users.
-
Return to the flow page.
-
Set the execution you just created to Required and click Config from the Actions menu in the same line.
-
Create a name for the execution and configure the authenticator.
-
From the sidebar, click Identity Providers and click your SSO provider.
-
Open the Post Login Flow menu and click the flow you just created.
-
Click Save.