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

Challo requires the following standard SAML attributes:

SAML attributesDescription
NameIDIdentifies 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.

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

Challo also provides the following optional SAML attributes:

Optional SAML attributesDescription
http://www.cafex.com/ws/2020/10/identity/claims/externalid
Challo 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

Challo provides SAML integration for the following identity management systems:

  • Microsoft Azure AD
  • Okta
  • OneLogin
  • PingFederate

Challo 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 Challo icon for your application.

  1. Configure Challo with attributes specific to your identity provider—see: Configuring Challo to use SAML.
  2. Challo generates the following attributes that your identity provider requires:
    • Challo SAML Entity ID
    • Challo SAML Assertion Consumer Service (ACS) URL
  3. Configure your identity provider with attributes for your Challo tenant—see: Configuring your identity provider to use SAML - See BELOW.
  4. Enable the service in Challo 

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

Configuring Challo to use SAML

  1. From your Challo menu, click Tenant settings

    mceclip0.png

  2. Click SAML authentication
  3. Provide the following attributes from your SAML server:
AttributeDescription
SAML server identifierA unique identifier of the SAML server, typically a URL, that Challo uses to connect to your domain’s SAML server.
SAML server login URLWhen someone logs in, Challo redirects to this URL to authenticate and sign in.
SAML Server logout URLWhen someone logs out, Challo 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 Challo.
Important: Certificates expire. You have to ensure that you keep the certificate to up date to continue using SAML for sign in.
  1. 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. Challo 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 Challo.
      Important:
      • If you enable this attribute and do not set up SCIM provisioning, no one from your organization can sign into Challo—see also: SCIM provisioning.
      • If you disable this attribute and do not set up SCIM provisioning, if a member of your organization signs into Challo, Challo associates them with your tenant in Challo.
    • SCIM to SAML attribute mapping
      Challo has to associate SCIM, SAML, and Challo records for individuals using an attribute mapping that you specify. Your identity management system may require specific configuration. See: SCIM and SAML mapping BELOW.
  2. Click Update.
  3. Challo generates two attributes your identity provider requires:
    • Challo SAML Entity ID
      Important: This is your organization’s specific URL that your members use to sign into Challo. After you enable SAML, the generic Challo sign in URL no longer provides access to Challo.
    • Challo 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 Challo —See: Azure -Understanding SAML-based single sign-on.
  2. Provide the following Single sign-on > User Attributes & Claims:
Azure AD SAML ClaimsExample 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 Challo before you create the application in Okta.

To setup Okta and Challo to use SAML:

  1. Important: In Challo, 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 Challo, 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 Challo SCIM provisioning guide for OneLogin.
  2. Provide the following Parameter:
SCIM provisioner with SAML fieldExample value
GroupsAs you require
NameIDEmail
SCIM UsernameUsername

PingFederate

To setup PingFederate and Challo to use SAML:

  1. Follow: Configuring a SAML application in PingFederate
    • Challo 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:
      • 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/externalid (optional)
        See: SCIM and SAML mapping BELOW.
      • 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, Challo has to map records between both protocols, to ensure provisioning and authentication records are for the same person.

As an administrator you choose how Challo 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 Challo associates records that match both attributes together; however, this is not always the case.

Challo provides the following mappings:

SCIM mapping to SAML attribute mappingDescription
SCIM ExternalID to SAML NameIDDefault.
Challo matches SCIM records that have an ExternalID value to SAML records that have the same NameID attribute value.
SCIM email address to SAML email addressChallo matches SCIM records that have the emails["work"] value to SAML records that have the same emailaddress attribute value.
SCIM ExternalID to Challo custom attributeChallo matches SCIM records that have an ExternalID value to SAML records that have the same Challo’s custom attribute (externalid) value.

Enabling SAML

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

  1. From your Challo menu, click Tenant settings

    mceclip0.png

  2. Toggle Enabled as you require
  3. Click Update

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

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