Add Microsoft ADFS as a single sign-on provider

Prerequisites:
  • Single Sign-on > Provider > Add, Delete, Edit, View permissions
  • Admin role in your organization’s ADFS account
  • User email addresses are the same in both ADFS and Genesys Cloud
  • Any Microsoft ADFS version that supports SAML 2.0. There are some differences in the configuration, depending on the version.

Add Genesys Cloud as an application that organization members can access with the credentials to their Microsoft ADFS account.

Notes:
  • Genesys Cloud does not support assertion encryption for single sign-on third-party identity providers. The Genesys Cloud log in service requires Transport Layer Security (TLS). Since the channel is encrypted, there is no need to encrypt parts of the message.
  • Administrators can optionally disable the default Genesys Cloud login and enforce authentication using an SSO provider only. For more information, see Configure Genesys Cloud to authenticate with SSO only.
  • Administrators can choose to store four additional certificates to ensure business continuity. If one certificate becomes invalid or expires, the integration is preserved if one of the additional certificates is valid. 

  • There is a general problem when a Service Provider (SP) receives a SAML response from an Identity Provider (IdP) and their system clocks are not in sync. This problem can result in users getting locked out of their single sign-on when logging in. The problem might be caused by the length of the clock skew between the SP and the IdP. Clock skews between Genesys Cloud and your identity provider cannot be greater than 10 seconds.

  • The Genesys Cloud desktop app does not support the installation of browser extensions. If you have configured an Azure Conditional Access policy that requires a browser extension, you will need to use a Genesys Cloud supported browser that has the Microsoft Entra ID extension installed. Single sign-on will not work using the desktop app in this configuration.

Configure Microsoft ADFS

Get the certificate for ADFS configuration

  1. In Genesys Cloud, click Admin.
  2. Under Integrations, click Single Sign-on.
  3. Click the ADFS/Azure AD (Premium) tab.
  4. Under Genesys Cloud Signing Certificate, click Download Certificate.
  5. Save the file.

Add a Relying Party Trust

  1. Go to Administrative Tools > AD FS. 
  2. In the console tree, go to AD FS > Trust Relationships > Relying Party Trusts.
  3. To open the wizard, click Add Relying Party Trust.
  4. On the Select Data Source page, click Enter data about the replying party manually.
  5. On the Specify Display Name page, enter a name for the replying party (that is Genesys Cloud).
  6. On the Choose Profile page, click AD FS profile to select SAML.
  7. Skip the Configure Certificate page.
  8. In the Configure URL page, do the following steps:
    1. Click Enable support for SAML 2.0 WebSSO protocol.

    2. In the field below the check box, type the following URL of your Genesys Cloud organization based on the AWS region.

      AWS Region

      URL
      US East (N. Virginia)

      https://login.mypurecloud.com/saml
      US East 2 (Ohio) https://login.use2.us-gov-pure.cloud/saml
      US West (Oregon)

      https://login.usw2.pure.cloud/saml 
      Canada (Canada Central)

      https://login.cac1.pure.cloud/saml
      South America (São Paulo)

      https://login.sae1.pure.cloud/saml
      EMEA (Frankfurt)

      https://login.mypurecloud.de/saml
      EMEA (Ireland)

      https://login.mypurecloud.ie/saml 
      EMEA (London)

      https://login.euw2.pure.cloud/saml
      EMEA (UAE)

      https://login.mec1.pure.cloud/saml
      EMEA (Zurich)

      https://login.euc2.pure.cloud/saml
      Asia Pacific (Mumbai)

      https://login.aps1.pure.cloud/saml
      Asia Pacific (Seoul)

      https://login.apne2.pure.cloud/saml 
      Asia Pacific (Sydney)

      https://login.mypurecloud.com.au/saml
      Asia Pacific (Tokyo)

      https://login.mypurecloud.jp/saml
      Asia Pacific (Osaka) https://login.apne3.pure.cloud/saml
  9. In the Configure Identifiers page, type a value for the Relying party trust identifier. The value can be any unique string that you want to use to identify the relying party trust. On identifying a relying party in a request to the Federation Service, AD FS uses prefix matching logic to determine a matching party trust in the AD FS configuration database.
  10. On the Configure Multi-factor authentication now page, choose whether to configure MFA.
    Note: This document does not cover the procedure to configure MFA.
  11. Leave all other settings at their defaults and click Close.
  12. On the Relying Party Trusts page, right-click the trust that you created in the previous procedure and select Properties.
  13. In the Endpoints tab, click Add SAML.
  14. For Endpoint Type, choose SAML Logout.
    AWS Region URL
    US East (N. Virginia) https://login.mypurecloud.com/saml/logout
    US East 2 (Ohio) https://login.use2.us-gov-pure.cloud/saml/logout
    US West (Oregon) https://login.usw2.pure.cloud/saml/logout 
    Canada (Canada Central) https://login.cac1.pure.cloud/saml/logout 
    South America (São Paulo) https://login.sae1.pure.cloud/saml/logout 
    EMEA (Frankfurt) https://login.mypurecloud.de/saml/logout
    EMEA (Ireland) https://login.mypurecloud.ie/saml/logout 
    EMEA (London) https://login.euw2.pure.cloud/saml/logout
    EMEA (UAE) https://login.mec1.pure.cloud/saml/logout
     EMEA (Zurich) https://login.euc2.pure.cloud/saml/logout
    Asia Pacific (Mumbai) https://login.aps1.pure.cloud/saml/logout
    Asia Pacific (Seoul) https://login.apne2.pure.cloud/saml/logout 
    Asia Pacific (Sydney) https://login.mypurecloud.com.au/saml/logout
    Asia Pacific (Tokyo) https://login.mypurecloud.jp/saml/logout
    Asia Pacific (Osaka) https://login.apne3.pure.cloud/saml/logout
  15. Click OK.
  16. In the Signature tab, click Add.
  17. Choose the certificate saved in step 5 of “Get the certificate for ADFS configuration” and click Open.
  18. Click OK.

Add the claim rules

Add three claim rules: Email, Email to NameID, and Org Name.

  1. On the Relying Party Trusts page, right-click the trust that you created in the previous procedure and select Edit Claim Rules.
  2. Add the Email rule:
    1. Click Add Rule. 

    2. Configure the claim rule with the following settings:

      Property Description
      Claim rule template Select Send LDAP Attributes as Claims.
      Claim rule name Type Email.
      Attribute store Select Active Directory.
      LDAP Attribute Select E-Mail Addresses.
      Outgoing claim type Select E-Mail Address.
    3. Click Finish.
  3. Add the Email to NameID rule:
    1. Click Add Rule.

    2. Configure the claim rule with the following settings:

      Property Description
      Claim rule template Select Transform an Incoming Claim.
      Claim rule name Type Email to NameID.
      Incoming claim type Select E-Mail Address.
      Outgoing claim type Select Name ID.
      Outgoing name ID format Select Transient Identifier.
      Pass through all claims Select Pass through all claim values.

    3. Click Finish.

  4. Add the Org Name rule:

    1. Click Add Rule.

    2. Configure the claim rule with the following settings:

      Property Description
      Claim rule template Select Send Claims Using a Custom Rule.
      Claim rule name Type Org Name.
      Custom rule

      Enter the following text, and replace OrgName with the shortname of your Genesys Cloud organization. The organization name is case-sensitive.  

      => issue(Type = "OrganizationName", Value = "OrgName");
    3. Click Finish.
  5. In the Issuance Transform Rules tab, make sure that the rules are in the following order:
    1. Email
    2. Email to NameID
    3. Org Name

SAML attributes

If the following SAML attributes are present in the assertion, Genesys Cloud acts on those attributes. The attributes are case-sensitive. 

Attribute name Attribute value
OrganizationName 
  • For identity provider-initiated single sign-on: Use the organization short name.
  • For service provider-initiated single sign-on: The organization name must match the organization that you select. Applicable when an organization maintains multiple Genesys Cloud organizations using a single identity provider. 
email  Email address of the Genesys Cloud user to be authenticated.
  • You must be an existing Genesys Cloud user.
  • If the identity provider does not use an email address as the subject NameID, you require a valid email address.
ServiceName 

(Optional) A valid URL for the browser to be redirected to after successful authentication, or one of the following keywords:

  • directory (redirects to the Genesys Cloud Collaborate client)
  • directory-admin (redirects to the Genesys Cloud Admin UI)

Get the certificate for Genesys Cloud configuration

  1. In the console tree, go to AD FS > Service > Certificates.
  2. Right-click the certificate under Token-signing and select View Certificate.
  3. Click the Details tab and click Copy to file.
  4. For the export file format, select Base-64 encoded X.509 (.CER).
  5. For the file name, do the following steps:
    1. Click Browse.
    2. Type a file name.
    3. Click Save.
  6. Click Finish.

Get the metadata for Genesys Cloud configuration

The metadata file contains the issuer (entityID) and the redirect URL for configuring Genesys Cloud.

  1. In the console tree, go to AD FS >  Service > Endpoints.
  2. Navigate to and download the file called FederationMetadata.xml.

Select authentication methods

Select the authentication methods for logging into Genesys Cloud on the extranet and the intranet.

  1. In the console tree, go to AD FS > Authentication Policies.
  2. Under Primary Authentication > Global Settings, click Edit.
  3. Under Extranet, check Forms Authentication.
  4. Under Intranet, check Forms Authentication and Windows Authentication.
  5. Click OK.

Configure Genesys Cloud

  1. In Genesys Cloud, click Admin.
  2. Under Integrations, click Single Sign-on.
  3. Click the ADFS/Azure AD (Premium) tab.

  4. Enter the Identity Provider metadata gathered from Microsoft ADFS.

    Field Description
    Certificate

    To upload X.509 certificates for SAML signature validation, do one of the following.

    1. To upload a certificate, click Select Certificates to upload.
    2. Select the X.509 certificate.
    3. Click Open.
    4. Optionally, to load a backup certificate, repeat steps 1–3.

    Or you can:

    1. Drag and drop your certificate file.
    2. Optionally, to load a backup certificate, repeat the first step.

    Uploaded certificates appear with their expiration date. To remove a certificate, click X.

    Note: To renew or update an expiring certificate, follow these instructions to upload X.509 certificates, repeating steps 1--3. You can upload up to five certificates to Genesys Cloud per SSO configuration, and Genesys Cloud chooses the correct certificate during single sign-on and logout.

    Issuer URI Enter the entityID from the FederationMetadata.xml file.
    Target URI

    Find the SingleSignOnService tag in the FederationMetadata.xml file with Binding equal to “urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect.” For example: <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://your-adfs.com/adfs/ls”>

    Use the URL contained in the “Location” attribute. For example: https://your-adfs.com/adfs/ls
    Single Logout URI

    Find the SingleLogoutService tag in the FederationMetadata.xml file with Binding equal to “urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect,” for example: <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://your-adfs.com/adfs/ls”>

    Use the URL contained in the “Location” attribute. For example: https://your-adfs.com/adfs/ls
    Single Logout Binding Select HTTP Redirect.
    Relying Party Identifier Add the unique identifier configured in step 9 when adding the Relying Party Trust. 
  5. Click Save.