Setting up single sign-on with the Okta IdP

Edit online

Configure single sign-on (SSO) with the SAML 2.0 protocol in Okta, by using the IBM® Envizi ESG Suite service provider metadata file in XML format. In the example, Envizi ESG Suite is the service provider (SP), and Okta is the identity provider (IdP).

Before you begin

Complete the following prerequisites:
  • Configure an Okta account that has administrative privileges.
  • Download the SP metadata file in XML format from the Envizi ESG Suite SSO settings page. The file typically includes the following information:
    • Entity ID, which is the SP identifier
    • Assertion Consumer Service (ACS) URL, where Okta sends SAML responses

About this task

The following procedure shows the generic steps to set up SSO in IdP applications. The steps are usually completed by system administrators who have access rights to manage their organization’s IdP application, typically from inside the IT department.

Envizi ESG Suite does not recommend any particular IdP. Instructions for setting up SSO with the SAML 2.0 protocol in an IdP application are subject to change with every new update that is released for the IdP application. For example, the following steps might change with each update that is released by Okta.

Procedure

  1. Create an SAML application in Okta:
    1. Log in to your Okta account and click the Applications tab.
    2. Click Create App > Integration, and select SAML 2.0 as the sign-in method.
    3. Enter a name for your application, for example, Your organization name-IBM Envizi SSO SAML 2, and click Next.
  2. Import the SP metadata:
    1. In the Configure SAML page, click Browse Files and upload the Envizi ESG Suite SP metadata XML file.
      Okta automatically extracts the following required configuration details:
      • ACS URL
      • Entity ID
      • Name ID format
    2. Review the SAML settings in Okta and modify the settings as necessary to match the following requirements:
      • The Audience Restriction or Audience URI matches the entity ID.
      • The Single Sign On URL value matches the ACS URL.
      • The Name ID format is EmailAddress. Ensure that the Name ID value matches the username that is in the Envizi ESG Suite system.
  3. Optional: Configure attribute statements:
    If just-in-time sign-in is required, map the Envizi ESG Suite required attributes to the corresponding Okta attributes.
    1. In the SAML Settings section, next to Attribute Statements, click Edit.
      For more information about the Envizi ESG Suite attributes claims that are required for just-in-time user provision, see Setting up just-in-time user provisioning, for example:
      1. NameID: ${user.email}
      2. FirstName: ${user.firstName}
      3. LastName: ${user.lastName}
      4. And so on...
    2. To save the changes, click Save.
  4. Assign users and groups:
    1. In the People tab, assign users and groups who need access to the Envizi ESG Suite SAML application.
    2. Ensure that the assigned users and groups have the necessary permissions to access Envizi ESG Suite.
    3. Optional: If just-in-time user provision is not required, consider including all users in the SSO application. Your organization’s IBM Envizi ESG Suite system administrator can then enable or disable users directly in Envizi ESG Suite without any changes in the IdP application.
  5. Configure the Envizi ESG Suite SP with Okta IdP metadata:
    1. In Okta, click the application Sign On tab.
    2. Click View Setup Instructions.
    3. Download the Okta IdP Metadata XML file or obtain the Identity Provider metadata URL.
    4. In Envizi ESG Suite, configure the IdP URL, which is the preferred option, or upload the Okta IdP Metadata XML file to the Envizi ESG Suite SSO settings page.
      For more information, see the Envizi ESG Suite SSO settings page.
  6. Test the SSO configuration:
    1. In Envizi ESG Suite, enable SSO from the SSO settings page.
    2. Configure one login in Envizi ESG Suite as a non-SSO login.
      If the SSO test fails, the login can be used to log back into Envizi ESG Suite by using the username and password.
    3. Use a test login to test the SSO configuration by accessing the Envizi ESG Suite application by using SSO. Ensure that the test login email address is set up as a login in Envizi ESG Suite and its logon method is SSO.
    4. Review the SSO testing guidance, and adjust the settings in Okta based on the test result.