Integrate Okta as an SSO Application Using SAML Protocol

This tutorial provides instructions on integrating Okta for single sign-on over the Security Assertion Markup Language (SAML) protocol.

Prerequisites

  1. You must have admin access to the Unifyia platform.
  2. You must have an active account with Okta with the necessary subscription.
  3. You must have users and groups in the Unifyia directory.
  4. Users must be assigned to groups that will have access to the Okta application within the Unifyia platform. A workflow needs to be created for these groups on the Unifyia platform.
  5. You will need the Unifyia platform endpoints. Follow the below steps to get the required endpoints:
    • Login to the Unifyia platform using admin credentials.
    • On the dashboard, navigate to Configurations > General Settings.
    • Under the section Endpoints, click on the link SAML 2.0 Identity Provider Metadata.The page with all the endpoint details is displayed.
    • Check the box Pretty-print to format the page.
    • Keep these details handy as you will need these values while adding the Unifyia platform as an IdP on the Okta application.
  6. You will also need to upload the issuer certificate for authentication. Follow the steps to create an issuer certificate in .pem format from the SAML metadata file.
    • In the SAML metadata file, locate the issuer X509 Certificate in base 64 format. Copy the certificate and paste it into a text file. Save the file with a .pem extension on your local machine, making sure to add the BEGIN and END Certificate lines at the beginning and end of the certificate content.

Step 1: Add the Unifyia Platform as a SAML IdP on Okta

  1. Log in to Okta with an admin account.
  2. On the dashboard, navigate to Security > Identity Providers.
  3. Select Add identity provider.
  4. The application displays a list of identity providers is displayed.
  5. Select SAML 2.0 IdP. Select Next.
  6. On the Configure OpenID Connect IdP page, define the following:
    • Name: Enter a name for the Identity Provider (Unifyia Platform) configuration, for example, Unifyia Platform.
    • IdP username: Enter the value as idpuser.email. The email of the user will be used in the SAML assertion for the username field.
    • Account Link Policy: Select the value as Automatic. This ensures that Okta automatically links an incoming IdP user to the matched Okta user.
    • Group Assignments: Select None.
    • Under the SAML Protocol Settings, provide the below values from the SAML 2.0 Identity Provider Metadata file that was mentioned under the prerequisites of this section.
      • IdP Issuer URI: Copy the value provided for entityIDfrom the file and paste it into this field. Make sure to copy the value within the quotes.
      • IdP Single Sign-On URL: Copy the value provided for the Location in the tag starting with from the file and paste it into this field. Make sure to copy the value within the quotes.
      • IdP Signature Certificate: Select Browse files... and upload the certificate file in the .pem format that was saved to your local machine. Refer to the Prerequisites of this section.
      • Retain the default values for the rest of the parameters.
    • Select Finish. A summary page that displays the configured parameters is displayed. Copy the Assertion Consumer Service URL and Audience URI values to a text editor and save them as you will need these values while configuring Okta as an SSO application on the Unifyia platform.
    • Select Edit profile and mappings. Under the Attributes section, select Mappings. The page to define the user profile mappings appears. There are two tabs - one to map the IdP (Unifyia Platform) to Okta and another to map Okta to IdP (Unifyia Platform).
      • IdP (Unifyia Platform) to Okta tab: You need to map the attributes as given in the below table. Once done, select Save Mappingsto save the values. Select Apply updates now to apply these mappings to all users with this profile.

SAML Attributes Mapping - OKTA for SSO

IdP (Unifyia Platform) to Okta Okta to IdP (Unifyia Platform) Description
appuser.email login Select the dropdown for the source.email and select email. You will notice that the attribute now changes to appuser.email. This means that the user's email will be used as a login credential.
appuser.firstName firstName Select the dropdown for the source.firstName and select firstName. You will notice that the attribute now changes to appuser.firstName.
appuser.lastName lastName Select the dropdown for the source.lastName and select lastName. You will notice that the attribute now changes to appuser.lastName.
appuser.email email Select the dropdown for the source.email and select email. You will notice that the attribute now changes to appuser.email.
Source.mobilephone By default, the mobile phone option is also available for mapping. Select the yellow key dropdown and select Do not map.

This completes the configuration of the Unifyia platform on the Okta application.

The next step is to configure Okta as an SSO application on the Unifyia platform.

Step 2: Configure Okta as an SSO Application

Prerequisites
  • You will need the Assertion Consumer Service URL and Audience URI from the previous step.
  • If you missed to copy the Assertion Consumer Service URL and Audience URI, on the Okta portal, navigate to Security > Identity Provider. Select Actions > Configure Identity Provider. Copy the required the details.

This section explains how to configure Okta as an SSO application on the Unifyia platform.

  1. Log in to the Unifyia platform as an administrator.
  2. Navigate to Integrations > SSO Applications. The SSO Applications page appears.
  3. Select + Add Application and from the drop-down menu, select SAML. The page to configure the SSO application appears. Adding an SSO involves two steps:
    • General Information: Provide application details and logo to display the application icon to the user.
    • SSO Configuration (SAML): Configure parameters to access the SSO application.
  4. Under General Information, enter the following:
    • App Name (required): Provide a name for the SSO application, for example, Okta_SAML
    • Description: Enter a brief description of the SSO application that you are adding.
    • Add a logo for the app: Either drag and drop a file or simply click the box to upload a logo for Okta. This logo will be displayed under the Applications panel on the User's dashboard once the user logs in to the Unifyia platform.
    • Select Next. You will be redirected to the next tab, SSO Configuration (SAML), where you'll configure the required OIDC parameters.
  5. Under the SSO Configuration (SAML) tab, set the below parameters for accessing the SSO application:
    • Client ID: Enter the Audience URI value that you have saved after completing the SAML configurations on the Okta application.
    • Redirect URIs: Enter the Assertion Consumer Service URL that you have saved after completing the SAML configurations on the Okta application.
    • Under the SAML Capabilities section, select the following values
      • NameID Policy Format:From the dropdown, select the value as Email.
      • Force POST Binding: Enable this option to direct the SAML protocol to exclusively use the POST Binding method for sending assertions.
      • Include AuthnStatement:Enable this option to enable the SAML login responses to include how (password) and when (timestamp of the login) a user was authenticated and the session expiration.
    • Under the Signature and Encryption section, select the following values
      • Sign Documents: Enable this option to sign the SAML document.
      • Sign Assertions: Enable this option to sign the SAML assertions.
      • Public Client: When enabled, the clients do not need to provide client secrets.
      • Signature Algorithm: Select RSA_SHA256 from the dropdown.
      • SAML Signature Key Name: Select None from the dropdown.
    • Under the Logout Settings section, ensure to disable the Front Channel Logout option as OKta does not support this option. The IdP server performs the background invocation of logout.
    • Under the Advanced section, provide values for the below parameters:
    • Assertion Consumer Service POST Binding URL: Enter the Assertion Consumer Service URL that you have saved after completing the SAML configurations on the Okta application.
    • Logout Service Redirect Binding URL: Enter the Assertion Consumer Service URL that you have saved after completing the SAML configurations on the Okta application.
  6. Select Add.
  7. The SSO application is successfully added. You will notice that 3 tabs are enabled - User Groups, Keys, and Mappers.
  8. Select the User Groups tab. A list of groups with existing workflows is displayed. Select the groups that should be granted access to the SSO application being created. You can choose multiple groups from the options provided. Select Update User Groups when done. You may also skip this step and choose the groups that can access this application at a later time.
  9. Select the Mappers tab. Create the 4 mappers that you have configured on the Okta application. Refer to the table below.

    10. SAML Attributes Mapping - Unifyia Platform for SSO

    Mapper Type Name Friendly Name Okta SAML Attribute Name SAML Attribute Name Format Unifyia Platform (IdP) User Attribute
    User Attribute username username username Basic email
    User Attribute email email email Basic email
    User Attribute firstName firstName firstName Basic firstName
    User Attribute lastName lastName lastName Basic lastName
  10. This completes the configuration of the Okta as an SSO application on the Unifyia platform.

Step 3: Test Configuration

Prerequisites
  • You must be a user of the groups that have access to the configured Okta SSO application.
  • You must have valid user credentials to access the Unifyia platform.

Follow the below steps to log in to the Okta application using the Unifyia platform credentials:

  1. Login to the Unifyia platform as a user.
  2. You will notice that the newly added application is listed on the dashboard under the Applications panel.
  3. Select the application. You will be logged into the Okta application.

Back Next
On this page
Related Links
How-To-Guides