Setting up SSO with SAML 2.0

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

Envizi supports SSO with your identity provider using SAML 2.0 authentication.

If your organization has been entitled for Single Sign-On (SSO), as a system administrator you can complete the SSO SAML 2.0 setup.

Note: currently not available to clients and is only available to implementation users with Partner Administration role. Once our implementation teams have more experience using this feature we will enable it for clients.

Setting up SSO

You will need to be a System Administrator in order to follow these steps:

Go to Admin → Single Sign-On
Click Create New SSO

Basic Metadata Configuration

Add a name/description to identify your SSO setup
Associate Name - keep the default value
Client ID - keep the default value
Entity ID - keep the default value (ensure that the url is …/home/ and not …/home1/ or …/home2/ etc)
ACS URL / Reply URL - keep the default value (ensure that the url that is included is …/home/ and not …/home1/ or …/home2/ etc)
Name ID format - keep the default value
Click the button Build and Download SP Data. This option will build the SP Metadata, save the metadata and download a xml file of the SP Metadata. This file needs to be sent to your IT department in order for them to register the Envizi application in your organization’s Identity Provider in order to generate a certificate and provide the IDP metadata as XML or URL for input into Envizi.

The SP (service provider) metadata contains information like the Entity ID and the Assertion URL and some configuration required for the Envizi application’s SSO configuration. This metadata will need to be imported to your Identity Provider when registering the Envizi application for SAML.

SP metadata example:

XML

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

Name ID (Name Identifier) must be formatted as email and must be the same as the username they will use to login into the system. Most IDP/organizations use the user’s email address as username and some uses a different username different from the email address.

Load IDP Metadata

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

From the SSO Setup grid, select the Action (or right-click) Edit SSO Metadata
Scroll down to STEP 2: Load IDP Metadata
Select XML or URL. If its a URL, you will be prompted with a text box to enter the URL of the metadata. If its an XML file, you will be prompted to upload the file. The system will automatically read the contents of the file and display in the text box for review.

URL is the preferred option as any changes in your IDP are automatically reflected and you will not need to upload a new xml file.

IDP metadata example, this will be provided either as a file or via a URL:

XML

<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>[email protected]</EmailAddress>
    </ContactPerson>

</EntityDescriptor>

Domain - leave blank if any users' email domains can be authenticated. If authentication is restricted to specific users' email domains, enter your organization's domain eg. %[@]ibm.com or %[@.]ibm.com. Please ensure that you do not enter proceeding and trailing spaces.
Toggle ON Enable Just-In-Time User Provisioning (if required).
Note: If enabled, additional configuration maybe required in both Identity Provider and Envizi System. Please refer to the Just-In-Time User Provisioning.
Toggle ON to Enable SSO when you have completed the above steps and you are ready for your users to login via SSO.
Click Save and Load Metadata to save all your changes.

Preference for Disabled Users being able to login

If your preference is to use a Login’s Enabled status to control whether they can log into Envizi or not:

On the row of the SSO you are configuring, select the Action (or right-click) Edit SSO Metadata
Click on Other Attributes
Toggle the Fail Disabled Users setting to ON (yes). Click Save.

If this setting is switched on, users who are authenticated via your identity manager but have their logins in Envizi set to disabled will not be able to login to Envizi.

Additional Information:

When manually provisioning users, ensure that the username is the same as they appear in the identity provider. Some identity providers do not always use an email address as the username but they are formatted to look like an email address.