Configuring SAML-based SSO in CRM portals

Configuring SAML-based SSO in CRM portals

This document will provide instructions on how to enable SAML-based SSO for your CRM's portal users. 
For an overview of SAML-based SSO, see SAML based Single Sign On (SSO) in CRM portals - Overview.
Prerequisite
Glossary
Prerequisite
  1. Editions: Enterprise and Ultimate
  2. Bundles (CRMPlus and Zoho One)
  3. Trial: No
  4. Developer: No
  5. Sandbox: No
  6. Mobile: No
  7. Permission: Users with the Manage Portals permission (Under Setup permissions > Admin level permissions) can configure SAML based SSO for their CRM's portal and manage it.

Glossary
  1. Authentication
  2. Authentication is the process of confirming a user's identity before providing access to a system. This is used to secure the system against impostors.
  3. SAML
    Security Assertion Markup Language (SAML) is a standard for communication that helps in authentication. It eases the exchange of authentication-related information between systems.
  4. SSO
    Single Sign On (SSO) is a method of authentication where a user needs to log in just once to access multiple apps and services. This improves user experience and security.
  5. IdP
    Identity provider (IdP) is a system that stores users' identities and authenticates them when they want to access an app or service. It helps improve the security of multiple systems by centralizing authentication and enabling SSO.
  6. SP
    Service provider (SP) is an app or service that a user wants to access.
  7. ACS URL
    Assertion Consumer Service (ACS) URL is where the IdP sends SAML responses. SAML responses are messages from the IdP to the SP that confirm a user's identity.
  8. Issuer
    Issuer is the unique identifier of an IdP or SP. It helps ensure that the SAML requests and responses are being sent to the right place. 
  9. Default Relay State
    This is the URL where the user lands after login authentication in IdP.
  10. Single Logout (SLO) URL
    This is the URL where the IdP sends the logout request.
  11. Login URL
    This is the login URL for the IdP. If a user isn't logged in to the IdP, they will be redirected to this page when they try to access an app or service.
  12. Logout URL
    This is the logout URL for the IdP. When a user logs out of an app or service managed by the IdP, the log out request is sent here.
  13. Public Key/ Certificate
    Public keys are used by SP and IdP to verify the signature and encrypt (or decrypt) SAML messages.
  14. Algorithm
    This is the algorithm used to encrypt and decrypt messages sent between the IdP and the SP.

SSO works because of communication between the IdP and SPs. To ensure that this happens smoothly, you've got to add some IdP-related details in the SP and vice versa. 
It is helpful to keep the following key details ready:
  1. Login URL (IdP-related, needs to be obtained from the IdP)
    This is the login URL for the IdP. If a user isn't logged in to the IdP, they will be redirected to this page when they try to access an app or service.
  2. Logout URL (IdP-related, needs to be obtained from the IdP)
    This is the logout URL for the IdP. When a user logs out of an app or service managed by the IdP, the log out request is sent here.
  3. Public Key/ Certificate (IdP-related, needs to be obtained from the IdP)
    Public key used by SP to verify the signature and encrypt (or decrypt) SAML messages from IdP.
Pre-requisite: 
Users with the Manage Portals permission (Under Setup permissions > Admin level permissions) can perform the steps mentioned below.
Notes
Point to remember: This configuration will be common for all portal user types created in that portal.

To enable SAML-based SSO for CRM portals

  1. Navigate to Setup > Channels > Portals.
  2. Click SAML configuration.

  3. In the popup that appears, do the following:

    1. Enter the Login URL from IdP
    2. Enter the Logout URL from IdP
    3. Enter the Public key/ certificate from IdP
    4. Copy the following details. You'll need to use them when you add the CRM portal to the IdP:
      1. Assertion consumer service(ACS) URL: The URL where the IdP sends SAML responses. 
      2. Issuer: The unique identifier of the SP.
      3. Default Relay State: The URL where the user lands after login authentication in IdP (when login is initiated by IdP)
      4. Single Logout (SLO) URL: The URL where the IdP sends the logout request
  4. Click Enable.
You've enabled SAML authentication for your CRM portal.

Next steps

  1. For the SSO to work, please ensure that:
    1. The CRM portal has been added as an SP/app to the IdP.
    2. The IdP-related details have been added correctly to the portal.
    3. The user has been added to the IdP.
  2. If any of the above conditions are not met, the user will be shown an error page.
Make sure the IdP is set up correctly, so users can begin using single sign-on in the CRM portal. The following details can be copied from the configuration popup seen in the instructions mentioned before. They can be used when you add the CRM portal as a SP to your IdP:
  1. ACS URL
    Assertion Consumer Service (ACS) URL is where the IdP sends SAML responses. SAML responses are messages from the IdP to the SP that confirm a user's identity. 
  2. Issuer 
    Issuer is the unique identifier of an SP. It helps ensure that the SAML requests and responses are being sent to the right place. 
  3. Default Relay State
    Default Relay State is the URL where the user lands after the IdP authenticates the user.
  4. Single Logout (SLO) URL
    This is the URL where the IdP sends the logout request to the SP.
Instructions for how to do this depend on the chosen IdP. Links to documentation of common IdPs can be found in the section below.

Configuring the Identity Provider

There are multiple IdPs like Zoho Vault, Okta, One Login, Auth0, Google Workspace, Microsoft Entra ID (formerly Azure Active Directory), Keycloak IDP, Zitadel IDP, etc. The ACS URL and Issuer details of the SP will need to be used here.

Please ensure that you've added the CRM portal as SP in the IdP. Instructions for the same can be found in that specific IdP's help documentation. The instructions for some commonly used IdPs can be found in the links below:

  1. Zoho Vault

  2. Okta

  3. One Login

  4. Auth0

  5. Google Workspace

  6. Microsoft Entra ID

Disabling SAML-based SSO

You may want to switch IdPs or let portal users log in with the credentials they'd used while signing up to the portal.

Pre-requisite
Users with the Manage Portals permission (Under Setup permissions > Admin level permissions) can perform the steps mentioned below.

Point to remember
If you disable SAML SSO for your portal, portal users will be able to log in to the CRM portal using the credentials they used when signing up.

To disable SAML-based SSO
  1. Navigate to Setup > Channels > Portals.
  2. Click View Details.
  3. In the popup that appears, click Disable.
Next step: To re-enable SAML authentication, follow the steps in the Enabling SAML-based SSO section.

See also
For learning more about setting up CRM portals, see: Setting up Portals and Inviting Users.