About Domino
Domino Data LabKnowledge BaseData Science BlogTraining

Keycloak Authentication Service

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:

Access Keycloak

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.

Retrieve the admin password

Before your first sign in, you must retrieve the admin password.

If you haven’t already, install kubectl and sign in to Kubernetes.

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

  2. Decrypt the password from the response:

    echo '<encrypted-password>' | base64 --decode

  3. Use this password to sign in to https://<your-domino-domain>/auth/ with the username keycloak.

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

Enable or disable user registration

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.

  1. In the Keycloak sidebar menu, click Realm Settings.

  2. Click the Login tab, and toggle User registration to On or Off.

  3. Click Save.

Local username and password configuration

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.

Configuration

In this mode the key settings are on the Login tab of the DominoRealm settings page.

image

Note

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.

image

Create a new realm or make changes to realms, including 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.

  1. From the Keycloak sidebar, go to Manage > Users.

  2. Select the admin account you want to assign the manage-users role to.

  1. Click the Role Mappings tab.

  2. For Client Roles, in Available Roles, click manage-users.

    image

  3. If you’re already signed in to Domino, sign out and then sign in again.

To activate or deactivate user accounts, see Manage Users.

LDAP / AD federation

When you choose federated authentication, Keycloak connects to the provider and caches user information.

Add a provider

  1. In the Keycloak console, go to the User Federation menu.

  2. 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 nameKeycloak 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.

  1. Use an LDAP mapper to import user attributes to Keycloak.

  2. Follow the steps in Synchronize SSO Group and Role related to Client Mappers to map from Keycloak to Domino.

Note

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.

Single sign-on (SSO) configuration

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)

  1. From the Keycloak sidebar menu, click Identity Provider.

  2. Select SAML v2.0.

    image

Configure alias and determine redirect URI

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

    keycloak add identity provider

    Note

Create a SAML endpoint in your upstream identity provider

  1. 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 policy format

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.

Assertion attributes

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 (if nameId is not an email or does not represent the username).

  • destination

No specific attribute names are expected as these can be mapped in Keycloak.

Important

Import metadata and complete configuration in Keycloak

Use the metadata file from the previous step to complete configuration of the provider in Keycloak.

Import IdP Metadata

  1. Go to the end of the identity provider configuration page.

    Note

    keycloak import external idp config

  2. Choose the file to import, then click Import.

    Most of the provider settings are configured automatically.

  3. Save the configuration.

Additional settings

After you’ve completed the initial configuration, confirm the following settings are configured correctly.

Email settings

Trust Email - Yes

Ensures that emails supplied from IdP are trusted even if Email Verification is enabled for DominoRealm.

image

Sync mode settings

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.

Username settings

NameID Policy Format

This was configured on import, but verify that it matches the option configured on the external endpoint.

Authentication settings

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

keycloak 1 4 2 additional saml settings

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.

Note
Export metadata from Keycloak

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.

Map first name, last name, and email

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.

keycloak 1 5 1 add identity provider mapper new

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 to First Name.

  • Friendly Name: FriendlyName attribute (optionally available) for the <saml2:Attribute> element that contains the value to be mapped to First 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 for Last 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 for Email.

  • User Attribute Name: email

Note

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:

keycloak 1 5 1 map firstname example

Alternatively, you can map this with:

keycloak 1 5 1 map firstname example2

Map username

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

      Map as shown:

      keycloak 1 5 2 email prefix as username

  • 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>
      <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>
      <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:

      keycloak 1 5 2 nameid persistent

Attribute mapping documentation

See Mapping Claims and Assertions for additional information on attribute mapping.

Email Prefix as Username Importer

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.

Troubleshoot attribute mapping

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:

image

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.

Note

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.

Prerequisites

The Domino Keycloak instance must have keycloak.profile.feature.scripts enabled.

Expected SAML attributes

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.

Attribute mapper

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>
Create the post-login authentication flow

By default, Domino doesn’t provide a post login flow so you must add one.

Add a post-login flow

  1. Create a Javascript file (such as authenticator.js) using the following script as an example.

    /*
* Template for JavaScript-based authenticators.
* 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));
}

  2. Create a JAR file with the following structure:

    META-INF/keycloak-scripts.json

authenticator.js

    The META-INF/keycloak-scripts.json is a file descriptor that provides metadata information about the scripts you want to deploy. It is a JSON file with the following structure:

    {
    "authenticators": [
        {
            "name": "New Authenticator",
            "fileName": "authenticator.js",
            "description": "Authenticator from a JS file"
        }
    ]
}

  3. Deploy the JAR file to the Keycloak server. Make sure to not accidentally overwrite existing files. Assuming the JAR file is called script.jar, run the following command:

    kubectl cp ./script.jar <domino-platform-namespace>/keycloakv18-0:/opt/jboss/keycloak/standalone/deployments/keycloak-resources

  4. Go to Authentication > Flows.

  5. Click New:

    image

  6. Create a generic flow named Post Login Flow.

    image

  7. In the new flow, click Add execution.

    image

  8. Select New Authenticator.

    image

  9. Make the execution required.

See Javascript providers for more information.

Customize the SSO button

  1. In Keycloak, go to the default domino-theme.

  2. 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
Tip

See the Keycloak documentation for more information about timeouts.

AWS credential propagation

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.

keycloak upstream idp trust

Validations in the AssumeRoleWithSAML workflow

  1. The Identity Provider Relying Party/Application validates the Issuer element in the AuthnRequest (SAML request) sent by Domino.

  2. Domino validates the Audience (Entity ID of the SP) in the SAML Response sent by the Identity Provider Relying Party/Application.

  3. AWS AssumeRole validates that the Issuer of the SAML Response passed on from Domino matches the Issuer of the Identity Provider Relying Party/Application. You can set up validations for other fields.

Launch a Workspace or execution

keycloak launching workspace run

Enable credential propagation in Domino

  1. 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 hour

      Example of a valid configuration:

      keycloak 2 1 enable cred prop

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

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

keycloak 2 2 3 attribute mapper

  • 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

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

keycloak 2 2 4 tokens

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.

  1. In the DominoRealm, go to the Clients tab and click domino-play.

    keycloak 2 3 1 domnio play

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

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

      keycloak 2 3 1 mappers2

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

Central configuration options

  • To enable this feature, you must update the Domino central configuration setting, authentication.oidc.externalOrgsEnabled to true, then restart Domino services.

Attribute mapper

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>

keycloak 3 1 3 mapper

Domino client mapper

When Domino is installed, it automatically creates the domino-group-mapper client mapper.

  1. To review the client mapper, go to Clients and click domino-play.

    keycloak 3 1 4 domino play

  2. Click the Mappers tab. You can see the domino-group-mapper.

    keycloak default client mappers

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.

Prerequisite

The SAML identity provider application connected to Domino must include attributes that can be mapped to specific Domino roles.

Central configuration

To enable this feature you must set the Domino central configuration setting, authentication.oidc.externalRolesEnabled to true, then restart Domino services.

Attribute mapper

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.

Domino client mapper

The domino-system-roles client mapper is created at installation.

  1. To review the client mapper, go to Clients and click domino-play.

    keycloak 3 2 4 client mapper

  2. Click the Mappers tab. You can see the domino-system-roles.

    image

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>

  • AWS Role Session Name

  • 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>

Limit concurrent user sessions

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:

Note

In addition, to limit concurrent sessions for API access, you must set up a Domino First Broker Login flow.

End user sessions

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

  1. Copy the default browser flow (this default flow can’t be customized directly).

  2. Click the copy of the default flow.

  3. Click the <Flow Name> Forms row from XYZ.

  4. From Actions, click Add Execution.

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

  6. Return to the flow page.

  7. Set the execution you created to Required.

  8. From the Actions menu, click Config.

  9. Create a name for the execution and configure the authenticator. For User Session Count Limiter, you can select Deny new session or Terminate oldest session as the desired behavior.

  10. Click Clients > domino-play.

  11. In Authentication Flow Overrides, from Browser Flow, click your copied browser flow, and click Save.

First broker flow for API access

  1. Copy the direct grant flow (this default flow can’t be customized directly).

  2. Click the copy of the default flow.

  3. Click Add Execution on the Actions menu.

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

  5. Return to the flow page.

  6. Set the execution you just created to Required and click Config from the Actions menu in the same line.

  7. Create a name for the execution and configure the authenticator. For User Session Count Limiter, you can select Deny new session or Terminate oldest session as the desired behavior.

  8. Click Clients > domino-play.

  9. 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:

  1. From the Keycloak sidebar, click Authentication.

  2. Click New on the Flow Definition page.

  3. Name the new flow, set the flow type to generic and click Save.

  4. Click Add Execution on the Actions menu.

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

  6. Return to the flow page.

  7. Set the execution you just created to Required and click Config from the Actions menu in the same line.

  8. Create a name for the execution and configure the authenticator. For User Session Count Limiter, you can select Deny new session or Terminate oldest session as the desired behavior.

  9. From the sidebar, click Identity Providers and click your SSO provider.

  10. Open the Post Login Flow menu and click the flow you just created.

  11. Click Save.

Domino Data LabKnowledge BaseData Science BlogTraining
Copyright © 2022 Domino Data Lab. All rights reserved.