Configure Single Sign-On via SAML

Applies to Collaborator 14.5, last modified on April 18, 2024

This topic describes how to establish single sign-on between an SSO server and Collaborator using Security Assertion Markup Language (SAML) protocol. To learn general principles of how single sign-on operates, see Single Sign-On.

In SAML terms, SSO server will act as Identity Provider (IdP) and Collaborator will act as Service Provider.

Below we describe how to establish single sign-on between Collaborator and OneLogin SSO server. Integration with Single Sign-On servers of other vendors is performed in a similar manner.

(Optional) Enable HTTPS Connections

Single sign-on servers mostly use HTTPS connections, so you will likely need to enable it for Collaborator server as well. For instructions, please see Configure HTTPS. Do not forget to restart the Collaborator server to apply changes.

Install and Configure SSO Server

  1. Install your preferred SSO server. In this instruction we will use OneLogin SSO server.

  2. Log in to your SSO server as account owner or super user.

  3. Add new application integration:

    • Select Applications > Add App from the main menu.

    • Search for an application of the SAML Custom Connector type.

      The Add App screen in OneLogin

      Click the image to enlarge it.

    • Specify the application display name and, optionally, its icons, then click Save.

    • Switch to the Configuration section and specify the following data:

      Audience The URL of the entity that is expected to receive the SAML message. In our case, this will be the URL of your Collaborator server.
      For instance: https://yourcollabserver.com.
      Your Collaborator server must be accessible to SSO server. Configure a firewall or enable tunneled connections to do so.
      ACS (Consumer) URL The URL of Assertion Consumer Service (ACS) where the SAML response will be sent to.
      Collaborator servers have this service at the following endpoint: https://yourcollabserver.com/services/saml/acs
      ACS (Consumer) URL Validator The regular expression to validate ACS URL.
      For instance: ^https:\/\/yourcollabserver\.com\/services\/saml\/acs\/$.
      Single Logout URL The URL of endpoint where the logout request will be sent to.
      Collaborator servers have the following logout endpoint: https://yourcollabserver.com/services/saml/logout

    • Switch to the Parameters section. Append assertion parameters with the following with names: FirstName, LastName, Email, Role, Department, Phone number, DisplayName and enable the Include in SAML assertion option for them. These parameters will respectively contain the users first name, last name, their role (regular user or administrator), and the name of their department.

      The app parameters in OneLogin

      Click the image to enlarge it.

      Please ensure, that parameters are named exactly as FirstName, LastName, Email, Role, Phone number, Department and DisplayName (including letter-case), since Collaborator would expect these parameter names in the assertion response. These parameters are not strictly required. If FirstName, LastName, Department or Phone number parameters are missing, new user accounts would obtain blank values for first name, last name, display name or department name, while existing accounts will keep the existing values of these parameters. If Role parameter is missing, or its value is not "admin" (case-sensitive), user account would obtain regular user role (even if this account had administrator role previously).

      Optionally, modify the NameID parameter to pass username rather than email address as primary user identifier.

      Optionally, add the MemberOf parameter (or other dedicated parameter) that will contain information about user membership in groups. See Synching User Group Membership with SAML Single Sign-On Server below.

      Alternatively, you can use the NameID parameter or add one more parameter to store LDAP user name for synchronizing group membership via LDAP or Active Directory. See Synching User Group Membership with LDAP/Active Directory below.

    • Click Save to confirm application configuration changes.

  4. Assign users to the created Collaborator SAML Connector application.

    • Select Users > All Users from the main menu.

    • Click the needed user.

    • Switch to the Applications section.

    • Click the plus sign to assign an app to the user.

      The user applications screen in OneLogin

      Click the image to enlarge it.

      Make sure that you have created at least one SSO account having admin privileges (Role = admin). If the User Role sync option is enabled, Collaborator will synchronize user roles between SAML and Collaborator servers. Users with admin privileges on the SSO server will automatically become administrators on Collaborator server. SSO accounts having any other value of the Role parameter will become regular users on Collaborator server.

      Collaborator is expecting SSO server response with only one attribute for the "Role" name. If server response contains multiple attributes with the "Role" name, Collaborator fetches the value of the last attribute.

  5. Select Applications from the main menu, click Collaborator SAML connector application, then switch to the SSO section.

    The application SSO section in OneLogin

    Click the image to enlarge it.

    This section holds identity provider SAML metadata that you must provide to your Collaborator server to complete the integration.

Configure Collaborator Server

  1. Open the Collaborator login page in a browser and log in to Collaborator as an administrator.

  2. In Collaborator, go to Admin > Single Sign-On.

  3. In the New SSO Configuration section select SAML SSO configuration type and click Create. This will display the configuration settings.

    The SAML settings page

    Click the image to enlarge it.

  4. Specify the setting values:

    Service Provider The URL of the entity that is expected to receive the SAML message. In our case, this will be the URL of your Collaborator server.
    For instance: https://yourcollabserver.com.
    Your Collaborator server must be accessible to SSO server. Configure a firewall or enable tunneled connections to do so.
    SSO login endpoint URL The URL where to redirect users for single sign-on procedure, if a session is not already established.
    This should be the value from the SAML 2.0 Endpoint (HTTP) setting of Collaborator SAML Connector application on SSO server.
    SSO logout endpoint URL The URL where to redirect users for single logout procedure.
    This should be the value from the SLO Endpoint (HTTP) setting of Collaborator SAML Connector application on SSO server.
    X.509 Certificate The public certificate that establishes trust between SSO server and Collaborator server.
    This should be the value from the X.509 Certificate setting of Collaborator SAML Connector application on SSO server.
    To copy the X.509 certificate, click View Details and click the Copy to Clipboard icon.
    Enable signature in SLO request

    Specifies whether to append digital signature to single logout requests.
    Signature type

    Specifies which type of signature to use. For HTTP-POST binding single logout requests use embedded xml attribute signature. For HTTP-Redirect binding single logout requests use signature as URL parameter.
    Enable AD/LDAP group sync Specifies whether Collaborator should retrieve user membership in groups from the LDAP/Active Directory. See Synching User Group Membership with LDAP/Active Directory.
    SAML NameIDPolicy Format

    Specifies the format of the NameIDPolicy parameter in the authentication requests.
    Username parameter

    Defines the name of SAML response parameter that contains LDAP username. See Synching User Group Membership with LDAP/Active Directory.

    If the parameter name is not specified, or the parameter returns empty value the synchronization is not performed.
    Enable SAML group sync

    Specifies whether Collaborator should synchronize its native groups with group information from the SAML single sign-on server.

    Once enabled, Collaborator will check user membership in groups in the SSO server and automatically add this user to the corresponding groups on the Collaborator server. If a group with the specified name does not exist, Collaborator will act according to the "Allow new group creation" and "Automatic group creation filter" settings below.

    See Synching User Group Membership with SAML Single Sign-On Server.
    Allow new group creation

    Specifies whether to create new groups on the Collaborator server when a group with the specified name does not exist. If enabled, Collaborator will create new group, if disabled Collaborator will only synchronize membership of existing groups.
    Automatic group creation filter

    A Java-style regular expression used to filter SSO groups before automatic group creation. Any group name that does not match the pattern will be excluded.
    MemberOf parameter

    Defines the name of SAML response parameter that contains information about user membership in groups.
    User Role sync

    Specifies whether to synchronize user roles between SAML and Collaborator servers, when syncing user membership with SAML SSO server.
    Create Collab user on login

    Specifies whether to create Collaborator user automatically on user login by SSO. Default value is true.

  5. After you specified the values, click Save. This will create a SAML SSO configuration.

  6. If you have multiple configurations, press Make Active to mark current configuration as active.

  7. Scroll the Admin > Single Sign-On screen up to the Single Sign-On (SSO) Status section and change the Enable Single Sign-On setting to Yes.

Now the integration between Collaborator and single sign-on server is configured and running. Further attempts to log into Collaborator server will be processed by the sign-on server.

SAML Metadata

SAML metadata is an XML file describing SAML entities in a standardized way. Identity provider and service provider could share their metadata to establish a baseline of trust and interoperability.

When SAML SSO integration is enabled, Collaborator publishes its service provider metadata at the following endpoint: https://yourcollabserver.com/services/saml/metadata

Sample service provider metadata

Synching User Group Membership with SAML Single Sign-On Server

You may configure user and group synchronization between Collaborator and your SAML single sign-on server. In this case, Collaborator will retrieve user properties (email, first and last name) and their membership in groups from the single sign-on server when the users login.

The login procedure will look like as follows:

  1. When user logs in, sign-on server sends SAML response with some pre-configured parameter which contains information about user membership in groups. This could be any existing parameter, like memberOf, or some other dedicated parameter.
  2. Collaborator receives the response and extracts the group names from the that parameter.
  3. Collaborator checks if some of existing user groups has matching name. Once such group is found, it adds the user to this group. Otherwise, it checks if the Allow new group creation setting is enabled and if the group name matches the Automatic group creation filter, creates new group on success and adds the user to the new group.
  4. Collaborator server logs the user in.

Technical details of SAML synchronization

Collaborator retrieves user membership from the SAML single sign-on server and checks if some of existing user groups has matching name. Once such group is found, it adds the user to this group. Otherwise, it checks if the Allow new group creation setting is enabled and if the group name matches the Automatic group creation filter, creates new group on success and adds the user to the new group.

Along with membership information, Collaborator is able to sync user permissions with SAML SSO server. If the User Role sync option is enabled, it will synchronize user roles between SAML and Collaborator servers. SSO accounts having admin privileges (Role = admin) will automatically become administrators on Collaborator server. SSO accounts having empty or any other value of the Role parameter will become regular users on Collaborator server.

Collaborator actualizes user properties, their membership in groups and permissions on every login. Such algorithm allows to keep a consistency between Collaborator and SSO server.

When SAML SSO integration is disabled or deleted, synchronized groups will become disabled.

Synching User Group Membership with LDAP/Active Directory

Alternatively, you may configure user membership synchronization between Collaborator, SAML single sign-on server and LDAP directory or Active Directory. In this case, Collaborator will use single sign-on server to manage users, but will query user membership from the LDAP directory or Active Directory.

The login procedure will look like as follows:

  1. When user logs in, sign-on server sends SAML response with some pre-configured parameters.
  2. Collaborator receives the response, extracts the parameter which holds LDAP username, and sends this username to LDAP directory or Active Directory.
  3. LDAP directory or Active Directory searches for groups this user belongs to and returns them to Collaborator
  4. Collaborator checks if the specified user and group(s) exist, creates them if needed, and adds the user to the group(s).
  5. Collaborator server logs the user in.

Configuration for LDAP/AD Synchronization

In order to enable synchronization of group membership via LDAP or Active Directory, you need to perform the following actions:

  1. Select/Create an SAML assertion parameter in user info section that will to store user's username. This could be any existing parameter, like NameID, FirstName or LastName, or some dedicated parameter.
  2. Modify Collaborator server's Root.xml (<Collaborator Server>/tomcat/conf/Catalina/localhost/ROOT.xml) to use the Combined Realm element:
    <Realm className="org.apache.catalina.realm.CombinedRealm" >
      <Realm allRolesMode="strictAuthOnly"
        className="org.apache.catalina.realm.DataSourceRealm"
        dataSourceName="/jdbc/collabserver"
        localDataSource="true"
        roleNameCol="user_admin"
        userCredCol="user_password"
        userNameCol="user_login"
        userRoleTable="user"
        userTable="user">
       <CredentialHandler
        className="org.apache.catalina.realm.MessageDigestCredentialHandler"
        algorithm="md5"
       />
    </Realm>

    <Realm allRolesMode="strictAuthOnly"
        className="org.apache.catalina.realm.JNDIRealm"
        connectionURL="ldap://ldap.example.com:389"
        userPattern="uid={0},dc=example,dc=com"
        roleBase="dc=example,dc=com"
        roleSearch="(&(objectClass=groupOfUniqueNames)(uniqueMember={0}))"
        connectionName="cn=read-only-admin,dc=example,dc=com"
        connectionPassword="password"
      />
    </Realm>

    The roleSearch parameter above defines the pattern used to identify user membership in a group. It uses standard LDAP query format syntax.

  3. Verify that the collaborator-authentication parameter remains true as for regular authentication:
    <Parameter description="Is the Collaborator database used for authentication?" name="collaborator-authentication" override="false" value="true"/>
  4. In ADMIN > General > SSO tabbed page set the Enable LDAP lookup setting to "Yes" and in Username parameter field specify the name of SAML assertion parameter that contains the LDAP username.

Technical details of LDAP/AD Synchronization

For mapping user membership in groups Collaborator uses the group's fully qualified domain name (FQDN) retrieved from the LDAP or AD. It checks if some of existing user groups has matching FQDN and adds the user to this group on success. Otherwise, it creates a new group and adds the user to the new group.

To name the new group Collaborator uses the first entry of group's fully qualified domain name (FQDN). For example, a group having the "ou=ccusers,dc=example,dc=com" FQDN will have the ccusers title. If some other group already has the same title, Collaborator will append the ordinal number to the group title: ccusers1, ccusers2 and so on.

On every login Collaborator checks existing groups created via LDAP or Active Directory synchronization and actualizes user membership in those groups. Such algorithm allows to keep a consistency between Collaborator and LDAP or Active Directory.

Troubleshooting

If you experience troubles with single sign-on authentication and cannot login to your Collaborator server (wrong redirect URLs, cannot login as admin, and so on), you can disable SAML single sign-on authentication via the -Dcom.smartbear.server.sso.disable=true Java VM option.

Known Issues With OneLogin Server

When users log out from OneLogin server, they still remain logged in Collaborator server. For some reason, OneLogin server does not trigger the Collaborator SLO endpoint when user logs out directly from OneLogin server. However, when users log out from Collaborator server, they will be logged out both from Collaborator server and from OneLogin server.

See Also

Configure Single Sign-On via Crowd OpenID
Configure HTTPS
Single Sign-On

Highlight search results