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 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.
Remember:

Ensure that you track your SSO certificate expiry date. Before the date of the SSO certificate expiry, either update your IdP URL or regenerate and re-upload your IdP metadata file into Envizi ESG Suite. The IdP URL option is simpler and therefore preferred for SSO configuration.

Procedure

  1. Go to Admin > Single Sign-On.
  2. Click Create New SSO.
  3. Configure basic metadata.
    1. Add a name and description to identify your SSO setup.
    2. 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 /homex.
      ACS URL / Reply URL Keep the default value. Ensure that the URL contains /home/, not /homex.
      Name ID format Keep the default value.
    3. 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.
  4. Work with your IT department to obtain either a URL, which is the preferred option, or an IdP metadata file that is in XML format.
    Pass the SP metadata file that you downloaded in step 3 to your IT department.
  5. Load IDP metadata.

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

    1. From the SSO Setup grid, right-click or select the Edit SSO Metadata action.
    2. Go to STEP 2: Load IDP Metadata.
    3. 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>
    4. 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
      For example, %[@]ibm.com is for the registration of email domains such as anything@ibm.com. %[@.]ibm.com is for the registration of email domains such as anything@au.ibm.com, anything@sg.ibm.com, anything@us.ibm.com and so on.

      Ensure that you do not enter preceding and trailing spaces.

    5. 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.
    6. Select Enable SSO.
    7. Click Save and Load Metadata.
    8. Before you start to use SSO, create a non-SSO login as a backup in case any issue occurs with the SSO setup, so that you can log back into the system with a non-SSO login to fix the problem.
      For more information about how to test the SSO configuration in Envizi ESG Suite, see Testing single sign-on configuration.
  6. 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.