Setting Up SAML

TABLE OF CONTENTS

• Required SAML Attributes
• Optional SAML Attributes
• Supported Identity Providers
• Configuring SAML
• Configuring CafeX to Use SAML
• SCIM to SAML Attribute Mapping
• Configuring Your Identity Provider to Use SAML
  • Microsoft Azure AD
  • Okta
  • OneLogin
  • PingFederate
• SCIM and SAML Mapping
• Enabling 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. 

When a user signs in, CafeX requests an authentication assertion from your Identity Provider’s (IdP) SAML server. CafeX uses this assertion to grant access to the CafeX service. SAML provides a single point of authentication that your organization manages, and CafeX does not store or request credentials.

Required SAML Attributes

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, SAML is used together with SCIM for provisioning and SSO. See also: Setting Up SCIM.

Optional SAML Attributes

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

Supported Identity Providers

CafeX provides SAML integration with the following identity management systems:

• Microsoft Azure AD
• Okta
• OneLogin
• PingFederate

CafeX may work with other identity providers; refer to their documentation for setup instructions.

Configuring SAML

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. Use the generated CafeX SAML Entity ID and Assertion Consumer Service (ACS) URL in your identity provider.
4. Configure your identity provider with attributes for your CafeX tenant. See: Configuring Your Identity Provider to Use SAML.
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. Click the three-dot menu in the page header and select Tenant settings.
2. Under Management, click SAML authentication.
3. Provide the following attributes from your SAML server:
   
   

   Attribute	Description
   SAML server identifier	The unique identifier (usually a URL) for your SAML server.
   SAML server login URL	URL where users are redirected for authentication during sign-in.
   SAML Server logout URL	URL where logout responses are sent when users sign out.
   SAML server certificate (Base64)	The Base64 public certificate to secure the transaction of SAML tokens. You need this certificate to establish trust between SAML server and CafeX. Important: Certificates expire. Ensure that you keep the certificate updated to continue using SAML for sign in.

4. As you require, select the following settings:
   Allow administrators to log in with non-SAML accounts (Recovery)
   This is helpful for recovery. 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.
   
   Only allow SAML login for users with SCIM provisioning
   This attribute ensures that only those that you provision with SCIM have access CafeX.
   Important:
   If you enable this attribute and do not set up SCIM provisioning, no one from your organization can sign into CafeX. For details, see Provisioning Users in CafeX.
   
   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.
   
   Enable groups
   Group support setting.

5. Click Update.

SCIM to SAML Attribute Mapping

CafeX must 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.

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

CafeX provides SAML integration for the following identity management systems:

• Microsoft Azure AD
• Okta
• OneLogin
• PingFederate

Microsoft Azure AD

To configure SAML integration between Microsoft Azure AD and CafeX:

1. In your Azure portal, create a non-gallery enterprise application for CafeX. See: Azure – Single sign-on SAML protocol.
2. Set user attributes under Single sign-on > User Attributes & Claims:

   Azure AD SAML Claims	Example Values
   Unique User Identifier (Name ID)	user.objectid Important: If SCIM is used, this attribute must match SCIM externalID.
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	user.mail
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	user.givenname
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	user.surname
   http://www.cafex.com/ws/2020/10/identity/claims/role Optional	To assign admin role from an Azure AD Group: set the User type to Members and select a Scoped Group – “ADMIN”

Okta

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

To configure SAML integration between Okta and CafeX:

1. Use a placeholder configuration in CafeX to generate the Entity ID and ACS URL that Okta requires.
2. Create the SSO integration in Okta. See: Okta – Build a Single Sign-On (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. See: OneLogin.
2. Provide the following parameters:

   SCIM Provisioner with SAML Field	Example Value
   Groups	As you require
   NameID	Email
   SCIM Username	Username

PingFederate

To setup PingFederate and CafeX to use SAML:

1. Follow Configuring a SAML Application in PingFederate.
2. Skip the Import Metadata step. CafeX does not support metadata publication.
3. Export the PingFederate certificate.
4. When you create the SP Connection, set the Value to uid.
5. Extend the SAML contract to include the following 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)
       Use externalid if needed. See: SCIM and SAML Mapping.
   5. http://www.cafex.com/ws/2020/10/identity/claims/role (optional)
      Use role only if SCIM does not assign roles such as “OWNER”, “ADMIN”, “STANDARD”.

SCIM and SAML Mapping

If you use both SAML and SCIM, CafeX must map records between the two protocols to ensure that user provisioning and authentication refer to the same individual.

As an administrator, you define 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

To enable or disable SAML integration with your identity provider:

1. Click the three-dot menu in the page header and select Tenant settings.
2. Under Management, click SAML authentication.
3. Toggle Enabled as you require.
4. Click Update to apply changes.

If SAML is disabled, users in your organization can sign into CafeX using other pre-existing authentication providers.

Important: If a member of your organization signs up to CafeX before you enable both SCIM and SAML, their account might be associated with a different CafeX tenant. Contact CafeX Support if you need to migrate these accounts.