Add Microsoft Azure AD as a single sign-on provider

Automatic Logout of SSO provider (single logout): Feature coming soon

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

Add Genesys Cloud as an application that organization members can access with the credentials to their Microsoft Azure AD Premium or Free Azure AD 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 one additional certificate to ensure business continuity. If one certificate becomes invalid or expires, the backup certificate will preserve the integration.

Configure Microsoft Azure AD

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

  1. Click Azure Active Directory > 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 type the appropriate Genesys Cloud SAML login URL in the Reply URL and Logout URL fields.
    The Identifier (EntityID) can be any value unique to the Azure instance. The Reply URL and Logout URL are based on the AWS region where your Genesys Cloud organization was created. See the following regions:
    AWS Region

    Reply URL

    Logout URL

    US East (N. Virginia)

    https://login.mypurecloud.com/saml

    https://login.mypurecloud.com/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

    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:

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

    • Refers to the email address for the user in Genesys Cloud. In most cases, this is user.userprincipalname, but if the Azure administrator has a different User Principal Name (UPN) and email, use user.email (may also be listed 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 a user logs in to AD as jsmith@company.com (user.userprinicpalname) but the user’s 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 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. You will use them to configure the Target URI and Issuer URI in Genesys Cloud.

    1. Click Azure Active Directory > 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 type the appropriate Genesys Cloud SAML login URL in the Reply URL and Logout URL fields.
      The Identifier (EntityID) can be any value unique to the Azure instance. The Reply URL and Logout URL are based on the AWS region where your Genesys Cloud organization was created. See the following regions:
      AWS Region

      Reply URL

      Logout URL

      US East (N. Virginia)

      https://login.mypurecloud.com/saml

      https://login.mypurecloud.com/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

      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 for the user in Genesys Cloud. In most cases, this is user.userprincipalname, but if the Azure administrator has a different User Principal Name (UPN) and email, use user.email.

        For example, if a user logs in to AD as jsmith@company.com (user.userprinicpalname) but the user’s 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 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. You will 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 application or a custom Genesys Cloud application, assign the users and groups that will log in to Genesys Cloud using Azure AD 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

    This 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/Azure AD (Premium) tab.
    4. Type the identity provider metadata gathered from Azure AD.

      In this field… Do this…
      Certificate

      1. Click Browse.
      2. Select the certificate you saved and click Open.
      3. Click Add .
      4. Optionally, to load a backup certificate, repeat steps 1-3. 

      Issuer URI

      Type the Azure AD Identifier from the Azure AD Genesys Cloud custom application.

      Note: This is a URL, not just the ID.  The URL should be 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 Azure AD Genesys Cloud custom application.
      Single Logout URI Type the Logout URL from the Azure AD Genesys Cloud custom application.
      Single Logout Binding Choose HTTP Redirect.
      Relying Party Identifier Type the Identifier (Entity ID) from the Azure AD Genesys Cloud custom application
    5. Click Save.

    Test the Azure AD Genesys Cloud application

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

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