Setting up SSO and SCIM provisioning for Genesys Cloud

Microsoft Entra ID

Do

• Confirm that your Genesys Cloud role grants Single Sign-on > Provider > Add, Delete, Edit and View permissions 75.
• Confirm that your Entra account holds the Application Administrator, Cloud Application Administrator or Application Owner role 17.
• Confirm that each person uses one email address in both Entra ID and Genesys Cloud 75.
• Note the regional login host that the SAML URLs will use, for example https://login.mypurecloud.com/saml 12.
• If you chose SCIM, note the regional API domain that forms the SCIM endpoint https://{domain}/api/v2/scim/v2/ 59.

Verify

• The Genesys integration page is at Menu > IT and Integrations > Single Sign-on, and the Entra app list is at Entra ID > Enterprise apps 63 3.
• Suggested check: open both administration pages with the accounts you will use and confirm that each one loads.

Okta

Do

• Confirm that your Genesys Cloud role grants Single Sign-on > Provider > Add, Delete, Edit and View permissions 75.
• Confirm that you hold an admin role in Okta, since Genesys requires an admin role in the identity provider 75.
• Confirm that each person uses one email address in both Okta and Genesys Cloud 75.
• If you chose SCIM, note the regional domain, for example api.mypurecloud.com (US East) or api.euw2.pure.cloud (London), because Okta asks for the regional SCIM Domain 59 37.

Verify

• The Genesys integration page is at Menu > IT and Integrations > Single Sign-on 63.
• Suggested check: open both administration consoles with the accounts you will use and confirm that each one loads.

Microsoft Entra ID

Do

• In Entra ID, go to Enterprise apps > New application, search the gallery for Genesys Cloud for Azure, and add it 3.
• Only 1 instance of this app can be configured for SSO in the tenant, because it uses a fixed identifier string 15.
• If you chose SCIM, note that Microsoft says the same app can carry provisioning but recommends a separate app when you first test the provisioning integration 13.

Verify

• Suggested check: confirm that the new application appears in the enterprise applications list.

Rollback

• Suggested rollback: delete the new enterprise application; nothing has changed on the contact center side yet.

Okta

Do

• Add the Genesys Cloud app from the Okta Integration Network, and under Sign On settings set Application username format to Email 38.

Verify

• Suggested check: confirm that the application is listed and that its username format shows email.

Rollback

• Suggested rollback: remove the application from the identity provider; nothing has changed on the contact center side yet.

Microsoft Entra ID

Do

• In the app's Basic SAML Configuration, set both Identifier and Reply URL to your region's Genesys login host plus /saml, for example https://login.mypurecloud.com/saml 12.
• For SP-initiated sign-in, set Sign-on URL to the regional login host without a path, for example https://login.mypurecloud.com 14.
• Keep the pre-populated Email attribute (source user.userprincipalname) and set OrganizationName to your organization name 2.
• Enter OrganizationName exactly, because Genesys treats it as case-sensitive, reads it as the org short name for IdP-initiated sign-in, and requires it to match the selected org for SP-initiated sign-in 74.
• From the SAML Signing Certificate section download Certificate (Base64), and from the Set up section copy the Login URL and the Microsoft Entra Identifier 1.

Verify

• Suggested check: reopen the SAML configuration and confirm that the identifier, reply and sign-on values all use your region's login host.
• Suggested check: confirm that the attribute list shows both the email and organization name attributes.

Rollback

• Suggested rollback: clear or correct the SAML settings on the application.

Okta

Do

• Obtain the SAML metadata file for the Genesys Cloud app from Okta, because importing the identity provider's metadata file into Genesys Cloud populates the required fields and signing certificate 63.
• If you send an OrganizationName attribute, enter it exactly, because Genesys treats it as case-sensitive, reads it as the org short name for IdP-initiated sign-in, and requires it to match the selected org for SP-initiated sign-in 74.

Verify

• Suggested check: confirm that you hold a metadata file for this application before moving on.

Rollback

• Suggested rollback: revert the SAML settings on the application.

Microsoft Entra ID

Do

• Go to Menu > IT and Integrations > Single Sign-on > Add an Identity Provider 63.
• If you have the identity provider's SAML metadata file, import it, which populates the required fields and the signing certificate 63.
• Otherwise, fill in the form, which holds Issuer URI, Single Sign-On URI and binding, optional request signing, Single Logout URI and binding, Name Identifier Format, and a ForceAuthn-on-inactivity option 66.
• For reference, Microsoft's tutorial maps the Entra values into a Genesys ADFS/Azure AD(Premium) tab: the certificate to ADFS Certificate, the Microsoft Entra Identifier to ADFS Issuer URI, the Login URL to Target URI, and the app's Application ID to Relying Party Identifier 6.
• Set Name Identifier Format, choosing Unspecified if you do not know it 66.
• Save, then use Download Metadata to get the Genesys service provider metadata, which contains the Issuer URI, Assertion Consumer Service and Single Logout URI for the identity provider 64.

Verify

• The Single Sign-on page shows each configuration's signing certificates with their expiration dates 65.
• Suggested check: confirm that the new integration is listed and that its certificate expiry date is in the future.

Rollback

• Suggested rollback: delete the new integration from the single sign-on page.
• While Genesys Cloud login is disabled, admins cannot delete every SSO provider 69.

Okta

Do

• Go to Menu > IT and Integrations > Single Sign-on > Add an Identity Provider 63.
• Import the Okta SAML metadata file, which populates the required fields and the signing certificate 63.
• Set Name Identifier Format, choosing Unspecified if you do not know it 66.
• Save, then use Download Metadata to get the Genesys service provider metadata (Issuer URI, Assertion Consumer Service and Single Logout URI) and load it into Okta 64.

Verify

• The Single Sign-on page shows each configuration's signing certificates with their expiration dates 65.
• Suggested check: confirm that the new integration is listed and that its certificate expiry date is in the future.

Rollback

• Suggested rollback: delete the new integration from the single sign-on page.
• While Genesys Cloud login is disabled, admins cannot delete every SSO provider 69.

Microsoft Entra ID + SSO only, with users created and maintained by hand in Genesys Cloud

Do

• Create each user in Genesys Cloud with Add Person, giving a full name and email, because Entra users must already exist as Genesys Cloud users before they can sign in 20.
• Use the same email address that the person's Entra account uses 75.

Verify

• Suggested check: open the people list and confirm that each pilot user exists with the expected email address.

Rollback

• Suggested rollback: deactivate the users you added for testing.

Microsoft Entra ID + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Go to Menu > IT and Integrations > OAuth, add a client with grant type Client Credentials, and assign only the SCIM Integration role 30.
• Include every division that SCIM will manage when you assign the role, because client credentials roles default to the Home division 31.
• If the SCIM Integration role is missing, restore the default roles with POST /api/v2/authorization/roles/default 32.
• Set the token duration, which defaults to 86,400 seconds and can be set up to 38,880,000 seconds (450 days) with the SCIM Integration role 33.
• Copy the client secret now, because it can be viewed only once at setup 34.
• Generate the bearer token by calling your region's login URL /oauth/token with the client ID and secret, as Genesys documents with its Postman collection 60.
• On the Entra app's Provisioning tab, set Provisioning Mode to Automatic, set Tenant URL to https://{domain}/api/v2/scim/v2/ and Secret Token to the bearer token, run Test Connection, and save 50 59 8.
• Leave Provisioning Status off for now, because Microsoft advises validating with on-demand provisioning for a few users before you select Start Provisioning 18.
• In the provisioning Properties, enable notification emails for quarantine and accidental deletions prevention, as Microsoft's steps say 11.
• Keep the required mappings: userPrincipalName to userName, which generates the Genesys user's main email address, and Not([IsSoftDeleted]) to active 62 42.
• Keep userName as the matching attribute, since it is the only one supported for filtering, and keep displayName, because userName, active and displayName are all required by Genesys Cloud 7.
• Do not rely on name.givenName, name.familyName or the address fields, which Genesys Cloud SCIM does not currently support 52.
• If users sign in with a non-email identifier, map that identifier to the Genesys externalIds extension keyed on the identity provider's Issuer URI 68.

Verify

• Test Connection checks connectivity to the Genesys SCIM endpoint 8.
• Suggested check: confirm that the connection test reports success and that the mapping list shows the user name as the matching attribute.

Rollback

• With Entra ID, mapping a previously synced field to an empty value does not clear it in Genesys Cloud 43.
• If the client secret is exposed, Generate new secret issues a new one 34.
• Suggested rollback: clear the provisioning credentials on the application and delete the OAuth client you created.

Okta + SSO only, with users created and maintained by hand in Genesys Cloud

Do

• Create each person's Genesys Cloud user with the email address that their Okta account uses, because Genesys requires a single email address shared by the identity provider account and Genesys Cloud 75.

Verify

• Suggested check: open the people list and confirm that each pilot user exists with the expected email address.

Rollback

• Suggested rollback: deactivate the users you added for testing.

Okta + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Go to Menu > IT and Integrations > OAuth, add a client with grant type Client Credentials, and assign only the SCIM Integration role 30.
• Include every division that SCIM will manage when you assign the role, because client credentials roles default to the Home division 31.
• If the SCIM Integration role is missing, restore the default roles with POST /api/v2/authorization/roles/default 32.
• Set the token duration, which defaults to 86,400 seconds and can be set up to 38,880,000 seconds (450 days) with the SCIM Integration role 33.
• Copy the client secret now, because it can be viewed only once at setup 34.
• Generate the bearer token by calling your region's login URL /oauth/token with the client ID and secret, as Genesys documents with its Postman collection 60.
• In Okta, under Provisioning > Integration, enter the regional SCIM Domain and the bearer token as API Token, select Test API Credentials, then Save 37.
• Under To App, enable the features you need from Create Users, Update User Attributes, Deactivate Users, Sync Password and Push Groups, each of which is optional 39.
• Decide on Sync Password with your password decision in mind: Sync Password creates a password for each user and pushes it to Genesys Cloud, while with Genesys Cloud login disabled all users must sign in by SSO 35 69.
• Store Okta phone numbers in E.164, because Genesys converts phone numbers from Okta to E.164 and other formats cause continual updates 36.
• Do not rely on name.givenName, name.familyName or the address fields, which Genesys Cloud SCIM does not currently support; the display name comes from displayName 52.

Verify

• Suggested check: confirm that the credentials test reports success and that only the provisioning features you chose are enabled.

Rollback

• If the client secret is exposed, Generate new secret issues a new one 34.
• Suggested rollback: turn off the provisioning features, clear the integration credentials, and delete the OAuth client you created.

SCIM sends the role and the division as user attributes + Microsoft Entra ID + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Create the target divisions in Genesys Cloud first, because the division value must match an existing division name or be blank 46.
• Map the division attribute, which Genesys writes to the user's divisionId 47.
• Confirm that the OAuth client you created includes every division that SCIM will manage 31.
• In Entra, create an app role for the Genesys role, assign it to the user, and map SingleAppRoleAssignment([appRoleAssignments]) to roles[primary eq "True"].value 55.
• Genesys maps the SCIM roles.[].value field to the user roles API, so the role values you send become Genesys role assignments 56.

Verify

• Suggested check: after the pilot run, confirm that each pilot user's role and division match the values sent from the identity provider.

Rollback

• Mapping a previously synced field to an empty value does not clear it in Genesys Cloud 43.
• Suggested rollback: remove the role and division mappings, then correct the affected users' roles and divisions by hand.

SCIM syncs group membership into Genesys groups that carry roles and divisions + Microsoft Entra ID + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Create one general group per access profile under Menu > User Management > Groups, with Visibility set to Public 25.
• Name each group identically to its Entra group, because groups must be created in Genesys Cloud first with identical names 4.
• Genesys SCIM supports only public groups, matches names case-insensitively, and cannot create or delete groups 54.
• On each group's Roles tab, select Assign Roles, enable the role and choose its divisions 23.
• Use no membership rules on these groups, because roles cannot be assigned to a group that has them 24.

Verify

• A role assigned on a group's Roles tab is granted to every current and future member 21.
• Suggested check: after the pilot run, confirm that members show the group's roles as inherited.

Rollback

• A group-granted role is removed from a user when they leave the group 21.
• Suggested rollback: remove the roles from the group before you delete or rename it.

SCIM sends the role and the division as user attributes + Okta + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Create the target divisions in Genesys Cloud first, because the division value must match an existing division name or be blank 46.
• Confirm that the OAuth client you created includes every division that SCIM will manage 31.
• Make sure Update User Attributes is enabled under To App, since it is one of the optional provisioning features 39.
• Send the role through the SCIM roles.[].value field, which Genesys maps to the user roles API 56.
• Send the division through scimEnterpriseUser.division, which Genesys maps to the user's divisionId 47.

Verify

• Suggested check: after the pilot run, confirm that each pilot user's role and division match the values sent from the identity provider.

Rollback

• Suggested rollback: remove the role and division mappings, then correct the affected users' roles and divisions by hand.

SCIM syncs group membership into Genesys groups that carry roles and divisions + Okta + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Create one general group per access profile under Menu > User Management > Groups, with Visibility set to Public 25.
• Name each group to match its Okta group, because Okta cannot create or delete Genesys groups and membership will not sync unless names match case-insensitively 40.
• On each group's Roles tab, select Assign Roles, enable the role and choose its divisions 23.
• Use no membership rules on these groups, because roles cannot be assigned to a group that has them 24.

Verify

• A role assigned on a group's Roles tab is granted to every current and future member 21.
• Suggested check: after the pilot run, confirm that members show the group's roles as inherited.

Rollback

• A group-granted role is removed from a user when they leave the group 21.
• Suggested rollback: remove the roles from the group before you delete or rename it.

SSO only, with users created and maintained by hand in Genesys Cloud

Do

• Create a general group under Menu > User Management > Groups, choosing its Type and Visibility 25.
• Open the group's Roles tab, select Assign Roles, enable the role and choose its divisions 23.
• Use groups without membership rules, because roles cannot be assigned to a group that has them and enabling roles discards its rules 24.
• Add users to the group; a role assigned on the Roles tab, with its divisions, is granted to every current and future member 21.

Verify

• Roles a user inherits from a group cannot be edited or removed on the user's own roles section 22.
• Suggested check: open a member's profile and confirm that the role appears there as inherited from the group.

Rollback

• To withdraw an inherited role, change the group's roles or the user's membership 22.

Granted in Genesys Cloud; SCIM carries identity and contact attributes only + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Leave the roles field and the optional division attribute out of the SCIM mapping, because Genesys maps roles.[].value to the user roles API and scimEnterpriseUser.division to the user's divisionId 56 47 46.
• Grant roles in Genesys Cloud through groups: open the group's Roles tab, select Assign Roles, enable the role and choose its divisions 23.
• Use groups without membership rules, because roles cannot be assigned to a group that has them 24.
• Do not hand-edit attributes that SCIM manages, because Genesys Cloud SCIM syncs one way and changes made in Genesys Cloud may be overwritten 61.

Verify

• Suggested check: after the pilot run, confirm that each pilot user's roles and division are unchanged.

Rollback

• To withdraw an inherited role, change the group's roles or the user's membership 22.

Microsoft Entra ID + SSO only, with users created and maintained by hand in Genesys Cloud

Do

• Test sign-in with Test this application (SP or IdP initiated), by browsing to the Genesys Sign-on URL directly, or from the Genesys tile in My Apps 19.
• Test both SP-initiated and IdP-initiated sign-in, since the app supports both 16.

Verify

• The Genesys login page shows the identity provider link, and Genesys says something in the configuration is incorrect if it does not appear 67.
• Only 6 SSO integrations appear directly on the login page 77.
• Suggested check: sign in as an administrator through single sign-on and confirm that you land in the correct org.

Microsoft Entra ID + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Keep the provisioning scope at Sync only assigned users and groups, which is the default 45.
• Assign a few pilot users, and if you chose group-based access, the matching groups; Entra provisioning only updates existing Genesys groups, matched on displayName 5.
• Validate with on-demand provisioning for those users, then select Start Provisioning, as Microsoft advises 18.
• Turn Provisioning Status on and save again 50.
• Test sign-in with Test this application, the Genesys Sign-on URL, or the Genesys tile in My Apps, covering both SP-initiated and IdP-initiated sign-in 19 16.

Verify

• Entra provisioning is monitored through the provisioning logs and the cycle progress bar, and an unhealthy configuration puts the app into quarantine 10.
• The Genesys login page shows the identity provider link, and Genesys says something in the configuration is incorrect if it does not appear 67.
• Suggested check: confirm that each pilot user appears in the people list with the expected email address.
• Suggested check: sign in as an administrator through single sign-on and confirm that you land in the correct org.

Rollback

• Removing a user from the app's scope makes the user inactive in Genesys Cloud 49.
• A hard delete in Entra, including the automatic hard delete 30 days after removal or soft delete, deletes the user in Genesys Cloud 48.
• Suggested rollback: turn provisioning off before removing pilot users from scope.

Okta + SSO only, with users created and maintained by hand in Genesys Cloud

Do

• Sign in as a pilot user through the identity provider link on the Genesys login page 67.

Verify

• The Genesys login page shows the identity provider link, and Genesys says something in the configuration is incorrect if it does not appear 67.
• Only 6 SSO integrations appear directly on the login page 77.
• Suggested check: sign in as an administrator through single sign-on and confirm that you land in the correct org.

Okta + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Assign a small set of pilot users to the app, noting that with Deactivate Users enabled, unassigning them later deactivates their Genesys accounts 35.
• If you chose group-based access, link the matching groups through Push Groups 40.
• Avoid Push Now, which can remove many members from a group and strip group-granted Genesys roles; Genesys SCIM blocks any single action removing more than 1,000 members 41.
• Sign in as a pilot user through the identity provider link on the Genesys login page 67.

Verify

• A pilot user's phone number should arrive in E.164, because Genesys converts Okta phone numbers to E.164 36.
• The Genesys login page shows the identity provider link, and Genesys says something in the configuration is incorrect if it does not appear 67.
• Suggested check: confirm that each pilot user appears in the people list with the expected email address.
• Suggested check: sign in as an administrator through single sign-on and confirm that you land in the correct org.

Rollback

• With Deactivate Users enabled, unassigning a user deactivates their Genesys account 35.
• Suggested rollback: unlink a pushed group rather than deleting the matching group on the contact center side.

Yes, disable Genesys Cloud login so users sign in by SSO only

Do

• Confirm that you do not use webhooks for chat notification integrations, because Genesys warns that this feature needs password-based authentication 73.
• Confirm that at least one third-party SSO provider is configured in the org, which SSO-only sign-in requires 71.
• Go to Menu > Account > Organization Settings > Authentication, select Disable Genesys Cloud Login, save, and accept the acknowledgment 70.

Verify

• With Genesys Cloud login disabled, the password requirement options are disabled but preserved, all users must sign in by SSO, and admins cannot delete every SSO provider 69.
• Suggested check: before saving, confirm that at least one administrator can sign in through single sign-on.

Rollback

• Clear Disable Genesys Cloud Login on the Authentication tab, save, and then reconfigure the password requirements 72.

No, keep Genesys Cloud credentials available alongside SSO

Do

• Leave Disable Genesys Cloud Login cleared under Menu > Account > Organization Settings > Authentication 70.

Verify

• The Genesys login page shows the identity provider link once SSO is configured 67.
• Suggested check: confirm that the login page still offers password sign-in alongside the single sign-on link.

Microsoft Entra ID + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• Removing a user from the app's scope or soft-deleting them in Entra makes the user inactive in Genesys Cloud 49.
• A hard delete in Entra, including the automatic hard delete 30 days after removal or soft delete, deletes the user in Genesys Cloud 48.
• Replace the Secret Token before the token duration you set runs out; that duration defaults to 86,400 seconds and can be at most 38,880,000 seconds (450 days) 33.
• Watch the provisioning logs, because an unhealthy configuration puts the app into quarantine 10.
• Add a renewed identity provider signing certificate while the current one is still listed; each configuration holds up to 5 certificates and Genesys picks the correct one at sign-in 65.

Verify

• The provisioning logs and the cycle progress bar show provisioning health 10.
• Suggested check: after each leaver, confirm that the person shows as inactive in the people list.

Rollback

• Suggested rollback: restore a mistakenly removed user in the identity provider before the automatic hard delete runs, so that the user is not deleted on the contact center side.

Okta + SSO with SCIM, so the identity provider creates and updates Genesys Cloud users

Do

• With Deactivate Users enabled, unassigning or deactivating a user in Okta deactivates their Genesys account 35.
• Replace the API Token before the token duration you set runs out; that duration defaults to 86,400 seconds and can be at most 38,880,000 seconds (450 days) 33.
• Add a renewed identity provider signing certificate while the current one is still listed; each configuration holds up to 5 certificates and Genesys picks the correct one at sign-in 65.

Verify

• The Single Sign-on page shows each certificate's expiration date 65.
• Suggested check: after each leaver, confirm that the person shows as inactive in the people list.

Rollback

• Suggested rollback: reassign a mistakenly removed user to the application and confirm that the account is active again.

SSO only, with users created and maintained by hand in Genesys Cloud

Do

• Add a renewed identity provider signing certificate to the configuration while the current one is still listed; each configuration holds up to 5 X.509 signing certificates and Genesys picks the correct one at sign-in 65.
• Without automatic provisioning, maintaining Genesys Cloud users is a manual task, so deactivate leavers in Genesys Cloud as well as in the identity provider 20.

Verify

• The Single Sign-on page shows each certificate's expiration date 65.
• Suggested check: after each leaver, confirm that the person shows as inactive in the people list.