Setting up SAML

As an an administrator you configure SAML (Security Assertion Markup Language) to exchange user authentication and authorization data between your identity management system and CafeX. By using SAML, members of your organization can sign into CafeX using your domain’s Single Sign-on (SSO) application. As someone signs in, CafeX requests an authentication assertion from your Identity Provider’s (IdP) SAML server. CafeX uses this assertion to give that person access to the CafeX service. SAML provides a single point of authentication that your organization manages and CafeX does not hold or request credentials.

CafeX requires the following standard SAML attributes:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Typically, you use SAML and SCIM together to provision and enable SSO for the members and groups of your organization. See also: Setting up SCIM.

CafeX has to associate SCIM, SAML, and CafeX records for individuals using an attribute mapping that you specify for your identity management system and organizational configuration.

CafeX also provides the following optional SAML attributes:

http://www.cafex.com/ws/2020/10/identity/claims/externalid

http://www.cafex.com/ws/2020/10/identity/claims/role

Configuring SAML

CafeX provides SAML integration for the following identity management systems:

• Microsoft Azure AD
• Okta
• OneLogin
• PingFederate

CafeX may work with other identity providers; follow their documentation for guidance.

As an administrator, to use SAML to enable single sign-on:

1. Set up a new application in your identity provider. Download and use the following CafeX icon for your application.
    
2. Configure CafeX with attributes specific to your identity provider—see: Configuring CafeX to use SAML.
3. CafeX generates the following attributes that your identity provider requires:
   • CafeX SAML Entity ID
   • CafeX SAML Assertion Consumer Service (ACS) URL
4. Configure your identity provider with attributes for your CafeX tenant—see: Configuring your identity provider to use SAML - See BELOW.
5. Enable the service in CafeX

Important: After you enable SAML, members of your organization have to use the value of the CafeX SAML Entity ID attribute to sign into CafeX. The value of this attribute is a URL that is specific for your organization and CafeX requires that you sign in using it. You cannot use the generic CafeX sign in URL to access CafeX. Any sign in attempts fail if you do not use your organization’s specific URL to access CafeX.

Configuring CafeX to use SAML

1. Open your profile menu > Tenant settings
2. Click SAML authentication
3. Provide the following attributes from your SAML server:

As you require, select the following settings:

• Allow administrators to log in with non-SAML accounts
   If your service provider is not available or you are troubleshooting a log in issue, this attribute allows, administrators to use an alternative provider to access their account. CafeX does not limit administrators to use their SSO service. This is helpful for recovery.

• Only allow SAML login for users with SCIM provisioning
  This attribute ensures that only those that you provision with SCIM have access CafeX.
   

Important:

1. If you enable this attribute and do not set up SCIM provisioning, no one from your organization can sign into CafeX—see also: SCIM provisioning.
2. If you disable this attribute and do not set up SCIM provisioning, if a member of your organization signs into CafeX, CafeX associates them with your tenant in CafeX.

SCIM to SAML attribute mapping

 CafeX has to associate SCIM, SAML, and CafeX records for individuals using an attribute mapping that you specify. Your identity management system may require specific configuration. See: SCIM and SAML mapping below.

1. Click Update.
2. CafeX generates two attributes your identity provider requires:
   • CafeX SAML Entity ID
     Important: This is your organization’s specific URL that your members use to sign into CafeX. After you enable SAML, the generic CafeX sign in URL no longer provides access to CafeX.
   • CafeX SAML Assertion Consumer Service (ACS) URL

Configuring your identity provider to use SAML

Use the following guides to configure your identity management system:

• Microsoft Azure AD
• Okta
• OneLogin
• PingFederate

Microsoft Azure AD

1. In your Azure portal, create a non-gallery enterprise application for CafeX—See: Azure -Understanding SAML-based single sign-on.
2. Provide the following Single sign-on > User Attributes & Claims:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

http://www.cafex.com/ws/2020/10/identity/claims/role

Okta

Okta requires that you generate the Entity ID and ACS URL in CafeX before you create the application in Okta.

To setup Okta and CafW to use SAML:

1. Important: In CafeX, use placeholder configuration to generate the Entity ID and ACS URL that Okta requires
2. Follow: Okta—Create your SSO integration.
3. Set SCIM to SAML attribute mapping to SCIM email address to SAML email address.
4. In CafeX, update your SAML configuration with the server identifier and server login URL from Okta

OneLogin

Typically, if you use OneLogin to provision users, you also configure SAML at the same time.

To complete SAML configuration:

1. Follow the CafeX SCIM provisioning guide for OneLogin.
2. Provide the following Parameter:

PingFederate

To setup PingFederate and CafeX to use SAML:

1. Follow: Configuring a SAML application in PingFederate
   • CafeX does not support metadata publication—ignore the Import Metadata step.
   • Export the PingFederate certificate
   • When you create the SP Connection, set Value to uid.
   • Extend the contract to include the necessary attributes:
     1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
     2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
     3. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
     4. http://www.cafex.com/ws/2020/10/identity/claims/externalid (optional)
         See: SCIM and SAML mapping BELOW.
     5. http://www.cafex.com/ws/2020/10/identity/claims/role (optional)
         If SCIM does not define: “OWNER”, “ADMIN”, “STANDARD”.

SCIM and SAML mapping

If you use SAML and SCIM, CafeX has to map records between both protocols, to ensure provisioning and authentication records are for the same person.

As an administrator you choose how CafeX maps SCIM records onto SAML records using the SCIM to SAML attribute mapping setting.

Typically, you can use SCIM ExternalID to SAML NameID so that CafeX associates records that match both attributes together; however, this is not always the case.

CafeX provides the following mappings:

Enabling SAML

As an administrator, to enable or disable SAML integration with your identity management system:

1. Open your profile menu > Tenant settings
2. Toggle Enabled as you require
3. Click Update

If you disable SAML configuration, members of your organization are able to go to CafeX and sign in using one of the pre-existing authentication providers.

Important: If a member of your organization signs up to CafeX , before you enable SCIM and SAML, it is possible that they belong to a different CafeX tenant. Contact CafeX support to migrate these accounts.