WikiSysop: Created page with "{{Article |Standalone=No |DisplayName=Provision SAML-based SSO |Context=Learn how to provision Security Assertion Markup Language-based single sign-on for private edition and..."

2022-05-19T15:16:01Z

Created page with "{{Article |Standalone=No |DisplayName=Provision SAML-based SSO |Context=Learn how to provision Security Assertion Markup Language-based single sign-on for private edition and..."

New page

{{Article
|Standalone=No
|DisplayName=Provision SAML-based SSO
|Context=Learn how to provision Security Assertion Markup Language-based single sign-on for private edition and mixed mode deployments when you do not have access to Agent Setup.
|ComingSoon=No
|Section={{Section
|alignment=Vertical
|structuredtext=This topic describes how to configure SAML 2.0 single sign-on integration between Genesys Authentication and third-party identity providers (IdP), such as Okta or Google.

{{NoteFormat|These instructions are for private edition or mixed mode deployments when Agent Setup is not available in your environment. If Agent Setup is available, see {{Link-AnywhereElse|product=PEC-AS|version=Current|manual=ManageCC|topic=Single_Sign-On}}.|3}}

Genesys Authentication works as a SAML service provider entity (SP). It accepts authentication assertions according to the SAML protocol and, if the assertion is valid, redirects to the application that started communication. In general, complete this configuration for each region in your deployment where you need SSO integration. However, there are a few global settings that are applicable to all regions—see {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=global|display text=Configure global settings}} for details.

The following diagram shows the communication flow for SAML-based SSO. All communication goes through the user's browser and there is no direct traffic or firewall filtering between the SP and the IdP.[[File:Auth_saml_sso.png|alt=A diagram illustrates single sign-on with Genesys as the service provider and the customer as the identity provider.]]Here's a breakdown of the SAML SSO process illustrated in the diagram:

#The user requests access to a resource.
#The SP redirects a SAML request to the IdP.
#The IdP challenges the user for credentials.
#The user provides the credentials and logs in.
#The IdP sends a signed SAML response to the browser.
#The browser posts the SAML response to the SP. Note: This diagram show SAML POST binding, which is selected by default. For a SAML redirect binding, #5 and #6 are merged into one arrow, similar to #2.
#The SP supplies the resource to the user.
|Status=No
}}{{Section
|sectionHeading=Prerequisites
|anchor=prerequisites
|alignment=Vertical
|structuredtext=You must have the following prerequisites to set up SAML-based SSO:

*Genesys Administrator Extension
*The identity provider metadata XML file generated by your IdP server. This file contains configuration and integration details for SAML SSO. For more information, see {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=metadata|display text=SAML metadata}}.
*The fully qualified domain name URL of your Genesys Authentication deployment. All endpoints in the SP metadata generated by Genesys Authentication use this URL.
*The administrator credentials: {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=Configure|anchor=services.secret.admin_username|display text=services.secret.admin_username}} and {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=Configure|anchor=services.secret.admin_password|display text=services.secret.admin_password}} from the '''values.yaml''' file.
*curl or any REST client.
|Status=No
}}{{Section
|sectionHeading=Configure SAML-based SSO
|anchor=config
|alignment=Vertical
|structuredtext=To configure SAML SSO for your deployment, complete the steps in this section. In the table below, you can find details about the parameters used in the configuration instructions.
{{{!}} class="wikitable"
{{!}}+
!Parameter
!Description
{{!}}-
{{!}}<auth-int-url>
{{!}}The Genesys Authentication internal ingress URL, as configured in {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=Configure|anchor=internal_ingress.frontend|display text=internal_ingress.frontend}}.
{{!}}-
{{!}}<auth-ext-url>
{{!}}The Genesys Authentication external ingress URL, as configured in {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=Configure|anchor=ingress.frontend|display text=ingress.frontend}}.
{{!}}-
{{!}}<ccid>
{{!}}Your contact center ID.
{{!}}-
{{!}}<region>
{{!}}The deployment region. For example, USW1.
{{!}}-
{{!}}<ops admin username>
{{!}}The user name of the operations administrator, as configured in {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=Configure|anchor=services.secret.admin_username|display text=services.secret.admin_username}}.
{{!}}-
{{!}}<ops admin pwd>
{{!}}The password of the operations administrator, as configured in {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=Configure|anchor=services.secret.admin_password|display text=services.secret.admin_password}}.
{{!}}}
{{AnchorDiv|global}}
===Configure global settings===
In Genesys Administrator Extension, [https://docs.genesys.com/Documentation/GA/9.0.0/user/CfgAccessGroup create an access group] for the SSO integration and add users to the group. Genesys recommends that you do the configuration with a test group and test users until you confirm that SSO is working correctly.

Next, configure the access group you want to use for the SSO integration. The '''value''' can be a comma-separated list. <syntaxhighlight>
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>/settings --data '
{"data":
{
"name": "samlAuthenticationAccessGroups",
"location": "/",
"value": "Test users",
"category": "saml"
}
}'
</syntaxhighlight>If needed, exclude an access group from SSO.<syntaxhighlight>

curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>/settings --data '
{"data":
{
"name": "internalUserAccessGroups",
"location": "/",
"value": "Internal Users,Super Administrators",
"category": "saml"
}
}
</syntaxhighlight>Optional—set the SAML user name option to identify the subject of a SAML assertion. This specifies which attribute in a SAML response is used as the user ID. The default value is <saml:NameID>.<syntaxhighlight>
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>/settings --data '
{
"data":
{
"name":"userNameAttributeKey",
"location":"/",
"value":<value>,
"category": "saml"
}
}
</syntaxhighlight>Optional—set the external ID option. If set to true, a user is identified by matching the user name from the SAML response with the '''external ID''' field from Configuration Server. If false, a user is identified by the '''username''' field in Configuration Server. <syntaxhighlight>
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>/settings --data '
{
"data":
{
"name":"useExternalUserId",
"location":"/",
"value":"true",
"category": "saml"
}
}'
</syntaxhighlight>

Optional—change the default SSO binding. Currently, Genesys Authentication supports POST (default) and Redirect bindings.<syntaxhighlight>
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>/settings --data '
{
"data":
{
"name":"ssoBinding",
"location":"/",
"value":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
"category": "saml"
}
}'
</syntaxhighlight>

===Configure regional settings===
Specify the settings for each region in your deployment. You must have a least one region. <syntaxhighlight>
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>/settings --data '
{
"data":
{
"name":"serviceProviderBaseURL",
"location":<region>,
"value":<auth-ext-url>,
"category": "saml"
}
}'
</syntaxhighlight>
Note: <region> must start with "/". For example, /USW1.

===Upload IdP metadata for the region===
Some IdP servers, like Okta, require you to submit service provider metadata before they generate IdP metadata. In this case, see {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=metadata|display text=SAML metadata}} before completing the following step.

Once you have the IdP metadata from your identity provider, upload it to Genesys Authentication. <syntaxhighlight>
curl -X POST -H "Content-Type: text/html" -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>/saml/<region> -d @<filename>

</syntaxhighlight>Note: <filename> is the name of your metadata file.

===Enable SAML===
To enable SAML, first get the data for your contact center.<syntaxhighlight>
curl -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid>
</syntaxhighlight>The response:<syntaxhighlight>
{

"status": {
"code": 0
},
"data": {
"id": "526af7ee-a71a-44a0-9eea-695eb46478d6",
"environmentId": "608b741c-99f3-4bb8-8456-4639088aff96",
"domains": ["somedomain.com"],
"auth": "configServer"
}
}
</syntaxhighlight>Copy the data object and change the value of '''auth''' to <code>saml</code>. Now POST the data back to the server:<syntaxhighlight>
curl -X PUT -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/environment/v3/contact-centers/<ccid> --data '
{
"data": {
"environmentId": "608b741c-99f3-4bb8-8456-4639088aff96",
"domains": ["somedomain.com"],
"auth": "saml"
}
}'
</syntaxhighlight>

===Settings propagation to secondary regions===
In multi-regional deployments, Genesys Authentication data propagates to the secondary region according to the data replication or propagation interval.

===Configure CORS===
Make sure to configure CORS settings to allowlist your IdP server endpoint URL. See {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=Provision|anchor=UpdateCORS|display text=Update CORS settings}} for details.
|Status=No
}}{{Section
|sectionHeading=Update configuration
|anchor=updateconfig
|alignment=Vertical
|structuredtext=You can update configuration by following the steps in {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=config|display text=Configure SAML-based SSO}} and then reloading the configuration. <syntaxhighlight>
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic <base64 encoded credentials>' -i <auth-int-url>/auth/v3/ops/saml/contact-centers/<ccid> --data '
{
"data":
{
"operation":"refresh"
}
}'
</syntaxhighlight>
|Status=No
}}{{Section
|sectionHeading=SAML metadata
|anchor=metadata
|alignment=Vertical
|structuredtext=Genesys Authentication works with two kinds of SAML metadata:

*{{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=idp|display text=Identity provider (IdP) metadata}}
*{{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=sp|display text=Service provider (SP) metadata}}

{{AnchorDiv|idp}}
===IdP metadata===
IdP metadata is a {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=prerequisites|display text=prerequisite}} to configure SAML-based SSO with Genesys Authentication. Some IdP servers (Okta, for example) might require you to submit SP metadata before they can generate IdP metadata. In this case, you must upload the IdP metadata to the Genesys Authentication service later in the configuration.

Make sure your IdP metadata is up to date with any changes that might affect communication between Genesys Authentication and the IdP server. For example, if you change to a different IdP or a certificate expires for your existing IdP.

Genesys stores IdP metadata as a plain text file in the Web Services and Applications Configuration database.

For example:<syntaxhighlight lang="json">
<auth-int-url>/environment/v3/contact-centers/<ccid>/saml/<region> -u <ops admin username>:<ops admin pwd>
</syntaxhighlight>

{{AnchorDiv|sp}}
===SP metadata===
You usually don't need the SP metadata. Retrieve it only when it is required to generate IdP metadata AND you don't want to {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=manual|display text=supply metadata entries to the IdP manually}}.

Genesys Authentication generates SP metadata automatically when configuration is successful for a particular region. You can access SP metadata as follows:<syntaxhighlight>
<auth-int-url>/auth/v3/saml/metadata/alias/sp-<ccid>-<region>-0
</syntaxhighlight>

{{AnchorDiv|manual}}
===Manual metadata entries===
To supply metadata entries to the IdP manually, you need the following information:

*The SP entity ID, also known as the Audience or Reference URI. This is the unique identifier of the service provider. For Genesys Authentication, you can calculate this ID as <code>sp-<ccid>-<region>-0</code>. Here's an example with a CCID of d49eab9b-ac85-4ad7-b9db-4197e6bc8020 and the region as USW1: <code>sp-d49eab9b-ac85-4ad7-b9db-4197e6bc8020-USW1-0</code>
*The single sign-on URL, also known as the AssertionConsumerService URI. For Genesys Authentication, the URL format <code><auth-int-url>/auth/v3/saml/SSO/alias/<SP entity ID></code>. Here's an example with the SP entity ID from the previous step: <code><nowiki>https://auth.myexamplecompany.com/auth/v3/saml/SSO/alias/sp-d49eab9b-ac85-4ad7-b9db-4197e6bc8020-USW1-0</nowiki></code>

*The single logout URL, also known as the SingleLogoutService URI. For Genesys Authentication, the URL format is <code><auth-int-url>/auth/v3/saml/SingleLogout/alias/<SP entity ID></code>. Here's an example with the SP entity ID from the previous step: <code><nowiki>https://auth.myexamplecompany.com/auth/v3/saml/SSO/alias/sp-d49eab9b-ac85-4ad7-b9db-4197e6bc8020-USW1-0</nowiki></code>

*The signature certificate, also known as an X509 certificate, from a certificate authority.
|Status=No
}}{{Section
|sectionHeading=Troubleshooting
|anchor=troubleshooting
|alignment=Vertical
|structuredtext=The first step in troubleshooting SSO issues is to check the SAML settings:<syntaxhighlight>
curl -X GET -H 'Authorization: Basic <base64 encoded credentials>' -i '<auth-int-url>/environment/v3/contact-centers/<ccid>/settings?category=saml'

</syntaxhighlight>

If you're seeing errors, particularly intermittent errors, try {{Link-SomewhereInThisVersion|manual=AuthPEGuide|topic=MixedProv|anchor=updateconfig|display text=reloading the configuration}} after checking the following:

*Make sure the IdP metadata is valid, including valid certificates.
*If the IdP delegates authentication to other entities, make sure that your CORS settings include all fully qualified domain names in the authentication path.
|Status=No
}}
}}

AUTH/Current/AuthPEGuide/MixedProv - Revision history

WikiSysop: Created page with "{{Article |Standalone=No |DisplayName=Provision SAML-based SSO |Context=Learn how to provision Security Assertion Markup Language-based single sign-on for private edition and..."