Add Microsoft Entra ID as a single sign-on provider

Prerequisites:
  • Single Sign-on > Provider > Add, Delete, Edit, View permissions
  • Admin role in your organization’s Microsoft Entra ID Premium or Free account
  • User email addresses are the same in both Entra ID and Genesys Cloud
  • Any Microsoft Entra ID Premium version that supports SAML 2.0 (differences in the configuration, depending on the version).
  • Or a free Microsoft Entra ID subscription that supports SSO

Add Genesys Cloud as an application that organization members can access with the credentials to their Microsoft Entra ID Premium or Free Microsoft Entra ID 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 Entra ID

You can either configure the Genesys Cloud gallery application (preferred method) or create a custom Genesys Cloud application.

  1. Click Microsoft Entra ID > Enterprise Applications.
  2. Click New Application.
  3. In the search box, type “Genesys Cloud for Azure.”
  4. Click the application, add a name to it, and then click Create.

    Note: Select the one published by Genesys Labs Inc.

  5. Click Single sign-on.
  6. Click SAML.
  7. In Basic SAML Configuration, click Edit and enter the appropriate Genesys Cloud SAML login URL in the Reply URL field, and enter the logout URL in the Logout URL field.
    The Identifier (EntityID) can be any value unique to the Azure instance. The table displays the Reply URL and Logout URL of your Genesys Cloud organization, based on the AWS region:
    AWS Region

    Reply URL

    Logout URL
    US East (N. Virginia)

    https://login.mypurecloud.com/saml

    https://login.mypurecloud.com/saml/logout
    US East 2 (Ohio)

    https://login.use2.us-gov-pure.cloud/saml

    https://login.use2.us-gov-pure.cloud/saml/logout
    US West (Oregon)

    https://login.usw2.pure.cloud/saml 

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

    https://login.cac1.pure.cloud/saml 

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

    https://login.sae1.pure.cloud/saml 

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

    https://login.mypurecloud.de/saml

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

    https://login.mypurecloud.ie/saml 

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

    https://login.euw2.pure.cloud/saml

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

    https://login.mec1.pure.cloud/saml

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

    https://login.euc2.pure.cloud/saml

    https://login.euc2.pure.cloud/saml/logout
    Middle East (UAE)

    https://login.mec1.pure.cloud/saml

    https://login.mec1.pure.cloud/logout
    Asia Pacific (Mumbai)

    https://login.aps1.pure.cloud/saml

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

    https://login.apne3.pure.cloud/saml

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

    https://login.apne2.pure.cloud/saml

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

    https://login.mypurecloud.com.au/saml

    https://login.mypurecloud.com.au/saml/logout
    Asia Pacific (Tokyo) https://login.mypurecloud.jp/saml https://login.mypurecloud.jp/saml/logout
  8. In User Attributes & Claims, click Edit and type these attribute names. To add a custom claim, type the custom attribute name in the Source attribute field above the drop-down list.
    Note: Attribute names are case-sensitive. Type them as they appear in the table. Do not use a namespace in claims.

    Attribute name Attribute value
    email 

    user.userprincipalname

    Notes:

    • For the email claim, create a new claim named email.

    • Refers to the email address of the user in Genesys Cloud. Usually, the email address is user.userprincipalname, but if the Azure administrator has a different User Principal Name (UPN) and email, use user.email (or as user.mail).

    • The case must match the case of the email address set up for that user in Genesys Cloud.

      Genesys Cloud changes email addresses to lowercase. If AD sends over the email with uppercase letters, for example John.Smith@company.com, you must add a lowercase transformation to the email claim. 

      1. In Manage claim, select Transformation.
      2. In Manage transformation, set Transformation to ToLOWERCASE().
      3. Set Parameter to user.mail.

    • The name claim must also match the email claim.

      For example, if you log in to AD as jsmith@company.com (user.userprinicpalname) but your actual email address in Genesys Cloud is john.smith@company.com, you can’t use user.userprincipalname. Use user.mail or user.email, depending on what you have in your Azure system. Do not enter namespace information.
      OrganizationName  Your Genesys Cloud organization short name
      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)
    • In the SAML Signing Certificate, click Certificate (Base 64) to download it.
    • Under Set Up Genesys Cloud for Azure, note the Login URL, Azure AD Identifier, and Logout URL. Use them to configure the Target URI and Issuer URI in Genesys Cloud.

    1. Click Microsoft Entra ID > Enterprise Applications.
    2. Click New Application.
    3. In Add an application, click Create your own application.
    4. In the Name field, type “Genesys Cloud.”
    5. Click Single sign-on.
    6. Click SAML.
    7. In Basic SAML Configuration, click Edit and enter the appropriate Genesys Cloud SAML login URL in the Reply URL field, and enter the logout URL in the Logout URL field.
      The Identifier (EntityID) can be any value unique to the Azure instance. The table displays the Reply URL and Logout URL of your Genesys Cloud organization, based on the AWS region:
      AWS Region

      Reply URL

      Logout URL
      US East (N. Virginia)

      https://login.mypurecloud.com/saml

      https://login.mypurecloud.com/saml/logout
      US East 2 (Ohio)

      https://login.use2.us-gov-pure.cloud/saml

      https://login.use2.us-gov-pure.cloud/saml/logout
      US West (Oregon)

      https://login.usw2.pure.cloud/saml 

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

      https://login.cac1.pure.cloud/saml 

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

      https://login.sae1.pure.cloud/saml 

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

      https://login.mypurecloud.de/saml

      https://login.mypurecloud.de/saml/logout
      EU (Ireland)

      https://login.mypurecloud.ie/saml 

      https://login.mypurecloud.ie/saml/logout
      EU (London)

      https://login.euw2.pure.cloud/saml

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

      https://login.aps1.pure.cloud/saml

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

      https://login.apne2.pure.cloud/saml

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

      https://login.mypurecloud.com.au/saml

      https://login.mypurecloud.com.au/saml/logout
      Asia Pacific (Tokyo) https://login.mypurecloud.jp/saml https://login.mypurecloud.jp/saml/logout
    8. In User Attributes & Claims, click Edit and type these attribute names. To add a custom claim, type the custom attribute name in the Source attribute field above the drop-down list.
      Note: Attribute names are case-sensitive. Type them as they appear in the table. Do not use a namespace in claims.

      Attribute name Attribute value
      email 

      user.userprincipalname

      Notes:

      • Refers to the email address of the user in Genesys Cloud. Usually, the email address is user.userprincipalname, but if the Azure administrator has a different User Principal Name (UPN) and email, use user.email.

        For example, if you log in to AD as jsmith@company.com (user.userprinicpalname) but your actual email address is john.smith@company.com, use user.mail or user.email, depending on what you have in your Azure system. Do not enter namespace information.

      • The case must match the case of the email address set up for that user in Genesys Cloud. Genesys Cloud defaults email to lowercase.

        If AD sends over the email with uppercase letters, for example John.Smith@company.com, you must add a lowercase transformation to the email claim. 
      OrganizationName  Your Genesys Cloud organization short name
      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)
    9. In the SAML Signing Certificate, click Certificate (Base 64) to download it.
    10. Under Set Up Genesys Cloud for Azure, note the Login URL, Azure AD Identifier, and Logout URL. Use them to configure the Target URI and Issuer URI in Genesys Cloud.

    Assign users and groups to the Genesys Cloud application

    After configuring either the Genesys Cloud gallery or a custom Genesys Cloud application, assign the users and groups to log in to Genesys Cloud using Microsoft Entra ID as the identity provider.

    1. In the Genesys Cloud custom application, click Users and groups.
    2. Click Add user.
    3. Click the appropriate users and groups.
    4. Click Assign.

    Configure Genesys Cloud

    Genesys Cloud configuration applies to both the Genesys Cloud gallery application and a custom Genesys Cloud application.

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

    4. Type the identity provider metadata gathered from Microsoft Entra ID.

      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

      Type the Azure AD Identifier from the Microsoft Entra ID Genesys Cloud custom application.

      Note: The issuer URI is a URL, not just the ID. Make sure that the URL is in the format “https://sts.windows.net/1234abcd5678efgh,” where the GUID is the Entity ID from Azure.
      Target URI Type the Login URL from the Microsoft Entra ID Genesys Cloud custom application. 
      Single Logout URI Type the Logout URL from the Microsoft Entra ID Genesys Cloud custom application.
      Single Logout Binding Choose HTTP Redirect.
      Relying Party Identifier

      Type the Identifier (Entity ID) from the Microsoft Entra ID Genesys Cloud custom application.


      Note: The SAML resource is the default for the app within Microsoft Entra ID. We recommend using the SAML resource as an Entity ID, as it is unique and readily available. If you are running multiple instances of the SSO integration on your Microsoft Entra ID instance, you can use a unique identifier as long as the IDP configuration in Genesys Cloud has the same identifier in the Relying Party Identifier field. Genesys Cloud uses this value to identify itself to the IDP.
    5. Click Save.

    Test the Microsoft Entra ID Genesys Cloud application

    The Microsoft Entra ID Genesys cloud application testing applies to both the Genesys Cloud gallery application and the custom Genesys Cloud application.

    • In the Single sign-on detail view in Microsoft Entra ID, click Test this application.