Introduction

Getting started

Walkthrough Guides

CafeX Apps

Workflows

Using CafeX Collaborate App

Reporting

Managing CafeX

Integrating CafeX

Security

Managing CafeX

Setting up SAML

Modified on Tue, 05 Sep 2023 at 02:46 PM

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:


SAML attributes

Description

NameID

Identifies the subject of a SAML assertion, that is typically the user who is being authenticated.

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

The e-mail address of the user.

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

The given name of the user.

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

The surname of the user.

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:


Optional SAML attributes

Description

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

CafeX custom attribute.
 Use to support custom SCIM to SAML record mapping—see: SCIM to SAML mapping BELOW.

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

If you do not have SCIM set up, you can use this attribute to specify a role for the user.
If you do have SCIM set up, this attribute is ignored. SCIM configuration overrides this value.
This attribute takes one of the following roles:
 “OWNER”, “ADMIN”, “STANDARD”

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.
     https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/73070412635/original/G5uPEl9i3sJcblX8Z-fkbFaZM3tChoFy-w.png?1693928766
  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:


Attribute

Description

SAML server identifier

A unique identifier of the SAML server, typically a URL, that CafeX uses to connect to your domain’s SAML server.

SAML server login URL

When someone logs in, CafeX redirects to this URL to authenticate and sign in.

SAML Server logout URL

When someone logs out, CafeX sends a logout responses back to SAML Server.

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. You have to ensure that you keep the certificate to up date to continue using SAML for sign in.

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:


Azure AD SAML Claims

Example values

Unique User Identifier (Name ID)

user.objectid
 Important: If you use SCIM, this attribute has to be the same as the SCIM externalID attribute.

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:
User type Members of 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 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:


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


SCIM mapping to SAML attribute mapping

Description

SCIM ExternalID to SAML NameID

Default.
CafeX matches SCIM records that have an ExternalID value to SAML records that have the same NameID attribute value.

SCIM email address to SAML email address

CafeX matches SCIM records that have the emails["work"] value to SAML records that have the same emailaddress attribute value.

SCIM ExternalID to CafeX custom attribute

CafeX matches SCIM records that have an ExternalID value to SAML records that have the same CafeX's custom attribute (externalid) value.

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.

 

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article