Setting up single sign-on

Edit online

Single Sign-On (SSO) describes the process of authenticating a user's identity with your organization’s central identity manager and then granting access to all of the applications that the user is authorized to access with that identity provider.

You can set up single sign-on in IBM® Envizi ESG Suite with your identity provider by using SAML 2.0 authentication.

Before you begin

Be aware of the following considerations when setting up and managing single sign-on:

Ensure that your organization is entitled to single sign-on.
Ensure that you are an implementation user with the Partner Administration role.
Ensure that you are a system administrator.
When manually provisioning users, ensure that the user name is the same as it appears in the identity provider. Some identity providers do not always use an email address as the user name but the user names are formatted to look like an email address.

Procedure

Go to Admin > Single Sign-On.
Click Create New SSO.

Configure basic metadata.

Add a name and description to identify your SSO setup.

Keep the following default values:

Table 1. SSO basic metadata configuration
Property	Value
Associate Name	Keep the default value.
Client ID	Keep the default value.
Entity ID	Keep the default value. Ensure that the URL contains /home/, not /home`x`.
ACS URL / Reply URL	Keep the default value. Ensure that the URL contains /home/, not /home`x`.
Name ID format	Keep the default value.

Click Build and Download SP Data.
This builds the SP (service provider) metadata, saves the metadata and downloads an XML file of the SP metadata. This file must be sent to your IT department so that the Envizi ESG Suite application can be registered in your organization’s Identity Provider to generate a certificate and provide the IDP metadata as XML or URL for input into Envizi ESG Suite.

The SP metadata contains information such as the Entity ID and the Assertion URL and some configuration required for the Envizi ESG Suite application’s SSO configuration. This metadata must be imported to your Identity Provider when registering the Envizi ESG Suite application for SAML.
For example:
```
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2023-12-09T00:01:55.297Z" cacheDuration="PT604800S" entityID="https://<cluster>.envizi.com/home/">
     <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
          <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
          <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<cluster.envizi.com/home/Client/Auth/AssertionConsumerService/<client_id>/" index="1"/>
     </md:SPSSODescriptor>
</md:EntityDescriptor>
```
Note: The Name ID (Name Identifier) must be formatted as email and must be the same as the user name that is used to login into the system. Most IDP/organizations use the user’s email address as the user name.

Load IDP metadata.

The IDP (identity provider) metadata contains the registration from your identity provider including certificates for authentication.

From the SSO Setup grid, right-click or select the Edit SSO Metadata action.
Go to STEP 2: Load IDP Metadata.

Select XML or URL.

Recommended: If you select URL, enter the URL of the metadata. URL is the preferred option as any changes in your IDP are automatically reflected without uploading a new XML file.
If you select XML, upload an XML file. The system automatically reads the contents of the file and displays it for review.

For example:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://w3id-prep.ice.ibmcloud.com/saml/sps/saml20ip/saml20">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://azuread.microsoft.com/saml/sso" />
        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://azuread.microsoft.com/saml/sso" />
        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://azuread.microsoft.com/saml/sso" />

        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://azuread.microsoft.com/saml/slo" />
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://azuread.microsoft.com/saml/slo" />
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://azuread.microsoft.com/saml/slo" />

        <ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://azuread.microsoft.com/saml/ars" index="0" />
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>

        <KeyDescriptor use="signing">
            <KeyInfo
                xmlns="http://www.w3.org/2000/09/xmldsig#">
                <X509Data>
                    <X509Certificate>IDP_PUBLIC_SIGNING_CERTIFICATE_USED_FOR_SIGNING_RESPONSES</X509Certificate>
                </X509Data>
            </KeyInfo>
        </KeyDescriptor>
    </IDPSSODescriptor>

    <Organization>
        <OrganizationName xml:lang="en-GB">Example</OrganizationName>
        <OrganizationDisplayName xml:lang="en-GB">Example Org</OrganizationDisplayName>
        <OrganizationURL xml:lang="en-GB">https://example.com/</OrganizationURL>
    </Organization>

    <ContactPerson contactType="technical">
        <Company>Example</Company>
        <GivenName>bob</GivenName>
        <SurName>smith</SurName>
        <EmailAddress>bob@example.com</EmailAddress>
    </ContactPerson>

</EntityDescriptor>

Indicate the domains that are allowed to authenticate with Envizi ESG Suite.
Leave the domain blank if any email address domain is allowed to authenticate with Envizi ESG Suite.
Enter allowed domains if only certain email address domains are allowed to authenticate with Envizi ESG Suite. For example, your organization's domain, or IBM:
```
%[@]ibm.com
```
or
```
%[@.]ibm.com
```
Ensure that you do not enter preceding and trailing spaces.
If required, enable just-in-time user provisioning. Doing so might require further configuration. For more information, refer to Setting up just-in-time user provisioning.
Select Enable SSO.
Click Save and Load Metadata.

Allow only enabled logins access to Envizi ESG Suite.
1. On the row of the SSO you are configuring, right-click or select the Edit SSO Metadata action.
2. Click Other Attributes.
3. Enable Fail Disabled Users.
  
  Selecting this option allows only enabled logins access to Envizi ESG Suite, and denies access to logins that have been disabled.
4. Click Save.