Add Okta as a single sign-on provider

Prerequisites:
  • Single Sign-on > Provider > Add, Delete, Edit, and View permissions
  • Admin role in your organization’s Okta account
  • User email addresses are the same in both Okta and Genesys Cloud

Add Genesys Cloud as an application that organization members can access with the credentials to their Okta 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 Okta

Get the certificate for Okta configuration

  1. In Genesys Cloud, click Admin.
  2. Under Integrations, click Single Sign-on.
  3. Click the Okta tab.
  4. Under Genesys Cloud Signing Certificate, click Download Certificate.
  5. Save the file.

Create a SAML application

  1. Create a SAML application for Genesys Cloud. Follow the instructions for setting up a SAML application in Okta in the Okta developer documentation.

  2. In the General > Single sign on URL field, type the 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

  3. In General > Audience URI, the value can be any unique string that you want to use to identify your Genesys Cloud organization.

  4. For General > Name ID Format, choose EmailAddress.

  5. Click Show Advanced Settings.

  6. For the General > Signature Certificate field, click Browse.
  7. Choose the certificate file saved in step 5 of “Get the Certificate for Okta Configuration.”
  8. Click Upload Certificate.

  9. Click the General > Enable Single Logout check box.

  10. In General > Single Logout URL, type the URL of your Genesys Cloud organization based on the AWS region.

    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
  11. Use the default values for other fields.
  12. Specify the organization so that Genesys Cloud users do not need to enter it when they log in. Create a new entry in Attributes Statements (Optional) with the following values: 
    Field Description
    Name Type OrganizationName.
    Name Format Leave set to Unspecified.
    Value Type the short name of your Genesys Cloud organization. If you do not know the short name of your organization, click Admin > Account Settings > Organization Settings in Genesys Cloud.
Note: No other options should be changed in the app configuration for Okta. For options such as Application Login Page and Application Access Error Page, the default option is preferred.

SAML attributes

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

Attribute name Attribute value
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 metadata for Genesys Cloud configuration

  1. In Sign on > Settings, click View Setup Instructions to display setup information.
  2. Note the following Identity Provider metadata that you need for the Genesys Cloud configuration. 
    Metadata Description
    Identity Provider Single Sign-on URL Use for the Target URI setting in Genesys Cloud.
    Identity Provider Single Logout URL Use for the Single Logout URI setting in Genesys Cloud.
    Identity Provider Issuer Use for the Okta Issuer URI setting in Genesys Cloud.
    X.509 Certificate Use for the Okta Certificate setting in Genesys Cloud.

Get the certificate for Genesys Cloud configuration

  1. On the Identity Provider metadata page, click Download certificate.
  2. Save the file as a .crt or .pem file.

Configure Genesys Cloud

  1. In Genesys Cloud, click Admin.
  2. Under Integrations, click Single Sign-on.
  3. Click the Okta tab.
  4. Provide the Identity Provider metadata gathered from Okta.
    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 Identity Provider Issuer.
    Target URL Type the Identity Provider Single Sign-on URL. 
    Single Logout URI Type the Identity Provider Single Logout URL.
    Single Logout Binding Choose HTTP Redirect.
    Audience (Entity ID)  Type the value used in step 3 of “Create a SAML application.”
  5. Click Save.