Integrate Okta as an IdP Using SAML Protocol

This tutorial provides instructions on integrating Okta as an indentity provider for identity federation over the Security Assertion Markup Language (SAML) protocol.

Prerequisites

  • You must have admin access to the Unifyia platform.
  • You must have an active account with Okta with the necessary subscription.
  • You must have people or groups in the Okta directory.
  • Create a group for the Okta IdP users and configure a workflow for it on the Unifyia platform.
  • If a group is not created and configured for the IdP on the platform and mapped to the IdP groups, then ensure to define a default workflow. This workflow would be assigned to all the users coming in from the IdP. Refer to the Create Workflow tutorial for more information.
  • The Unifyia platform needs to be configured as an application on the Okta application.
  • You will need the Unifyia platform's Single Sign-On URL and Audience URI (SP Entity ID) copied from the SAML configuration page.
  • You will need to upload the issuer certificate in .pem format to the Okta application for authentication.

How to get a Single Sign-On URL and Audience URI (SP Entity ID)?

  1. Log in to the Unifyia platform as an administrator.
  2. Navigate to Integrations > Data Sources > Identity Provider. The Identity Provider page appears.
  3. Select + Add Identity Provider and from the drop-down menu, SAML v2.0.
  4. Navigate to the IdP Configuration (SAML v2.0) tab. You will find the Redirect URL displayed on the page. The format of the URL will be as below: 
    5.   https://<tenantname>.<domainname>.net:<port>/realms/<tenantname>/broker/<alias>/endpoint
  5. First, add an Alias to uniquely identify the platform tenant, for example, okta_idp_saml
  6. You will notice that the Redirect URL has changed. The given alias name is now added just before /endpoint.
  7. This is the Single Sign-On URL for the platform. Copy it to a text editor.
  8. Next, scroll down, to find the Service Provider Entity ID. Copy it to the text editor.

How to get a .pem issuer certificate file?

Follow the steps to create an issuer certificate in .pem format.

  1. Login to the Unifyia platform using admin credentials.
  2. On the dashboard, navigate to Configurations > General Settings.
  3. Under the section Endpoints, click on the link SAML 2.0 Identity Provider Metadata. The page with all the endpoint details is displayed.
  4. 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. The BEGIN and END certificate lines must contain exactly five dashes (-----BEGIN CERTIFICATE-----) on each side with no spaces in between the dashes. If there are more or fewer dashes, the certificate upload will fail.
  5. Keep the metadata file handy as you will need certain values from this file.

Step 1: Add Unifyia as an Application on Okta

This section provides instructions on how to add Unifyia as an application on Okta.

  1. Log in to Okta with an admin account.
  2. On the Dashboard, navigate to Applications > Applications.
  3. On the Applications page, select Create App Integration.
  4. On the Create a new app integration pop-up, select SAML.
  5. Select Next.
  6. Enter the following information on the Create SAML Integration page.
    1. General Settings tab:
      1. App Integration Name: Enter the name of the application you are adding, for example, Unifyia Platform.
      2. Logo: Upload a logo of your organization or the application.
      3. Check Do not display the application icon to users if you do not want the icon to be visible.
      4. Select Next. You are redirected to the Configure SAML tab.
    2. Under the SAML Settings section enter the following details:
      1. Single sign-on URL: Enter the Single Sign-On URL that you have built using the Redirect URL and copied to a text editor.
      2. Audience URI (SP Entity ID): Provide the Service Provider Entity ID copied to the editor.
      3. Name ID format: Select the value EmailAddress from the dropdown.
      4. Select the link Advanced Settings and enter the following details:
      5. 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 section.
      6. Select the option Allow application to initiate Single Logout.
      7. Single Logout URL: From the SAML metadata file that you have, search for SingleLogoutService, copy the URL for the location parameter, and paste it for this value.
      8. SP Issuer: Provider the Service Provider Entity ID value from the text editor. Audience URI and SP Issuer take the same value., i.e. Service Provider Entity ID.
      9. Select the option Validate SAML requests with signature certificates.
    3. Under the Attribute Statements section, you need to define which attributes must be mapped. Refer to the table below for the list of Attribute Mappers to be configured on the Okta application. Once completed, select Next.
      4. Name (Attribute Name) Name Format Value
      Username Basic email
      email Basic email
      firstName Basic firstName
      lastName Basic lastName
    4. Select the option I'm an Okta customer adding an internal app.
    5. Select Finish.
    6. The summary page displays the metadata URL. Copy this to a text editor.
    7. You will find the SAML Setup section at the bottom right corner. Select View SAML setup instructions. A page with Okta's SAML metadata appears. Keep this information handy. You will find the logout URL on this page.

Step 2: Configure Okta as a SAML IdP on the Unifyia Platform

Prerequisites

  • You need the SAML setup metadata from Okta.
  • Ensure to provide the same alias name (for example, okta_idp_saml) that you have added to build the Single sign-on URL.
  • Open a browser and paste the Okta metadata URL to open the Okta metadata.
  • You will require the following metadata values and URLs of Okta.
    • SAML Entity Descriptor (from the summary page that you copied to the text editor.)
    • If SAML Entity Descriptor is not provided, check for the below data in the Okta SAML instructions.
      • Single Sign-On Service URL
      • Service Provider Entity ID
      • Single Logout Service URL
      • X509 Certificate of the IdP

Integration Steps

  1. Log in to the Unifyia platform as an administrator.
  2. Navigate to Configuration > Data Sources > Identity Providers. The Identity Providers page appears.
  3. Select + Add Identity Provider and from the drop-down menu, select SAML v2.0. The page to configure the identity providers opens. Adding IdP involves two steps:
    1. Adding the General Information
    2. Configuring parameters for IdP Configuration (SAML v2.0)
  4. Under the tab General Information, enter the following:
    1. App Name(required): Provide a name for the IdP, for example, OktaIdP_SAML
    2. Description: Enter a brief description of the identity provider and the application you will be using it with.
    3. Add a logo for the app: Either drag and drop a file or simply click to upload a logo for the IdP.
    4. Select Next. You will be directed to the next tab, IdP Configuration (SAML v2.0), where you'll configure the necessary SAML parameters.
  5. Under the IdP Configuration (SAML v2.0) section, set the below parameters:
    1. Alias: Provide the same alias name, for example, okta_idp_saml. that you have added to build the Redirect URI.
    2. Domain Name: Provide the domain name of your organization, for example, utopia.com.
    3. Endpoints:Click on the link SAML 2.0 SERVICE PROVIDER METADATA to get the Unifyia Platform metadata to configure in the IdP server. This metadata file is generated correctly only after you save the configuration.
    4. Under SAML Settings, configure the following:
      1. Use Entity Descriptor: Enable this option if you want to use the SAML Entity Descriptor. This will acquire the required data from the metadata file copied from the summary page on Okta. If you disable this option, you need to provide the below values from the SAML metadata file from Okta:
        1. Single Sign-On Service URL: Provide the Identity Provider Single Sign-On URL.
        2. Identity Provider Entity ID: Search for the entityID on the metadata file and copy it. Provide this value for this parameter.
        3. Single Logout Service URL: Provide the Identity Provider Single Logout URL. View SAML setup instructions page from Okta to get this value.
      2. SAML Entity Descriptor: You copied a URL from the summary page of the Okta configuration to a text editor. Copy and paste the URL from the text file. If you provide this value, then the
        1. Single Sign-On Service URL, Identity Provider Entity ID, Single Logout Service URL, and Validate Signatures values are auto-populated.
        2. Validate Signatures flag is enabled and it acquires the certificate from the metadata URL.
        3. Allow Create, HTTP-POST Binding for AuthnRequest, and HTTP-POST Binding Response flags are enabled.
      3. Client session logout: Enable this option if the SAML logout must also end the session of your client.
        4. NOTE
        This must be supported by your identity provider. This can also be referenced as back-channel logout. You may leave it disabled if it is not supported by your identity provider.
      4. NameID Policy Format: Select the option Email from the dropdown.
      5. Principal Type: Denotes which part of the SAML assertion is used to identify and track the user identities. Select Subject Name ID from the dropdown.
      6. Allow Create: Enable this option if you want to allow the identity provider to create a new identifier.
      7. HTTP POST Binding Response: Enable this option if you want to allow the SAML response from the IdP to the SP to be sent using the HTTP-POST method.
      8. HTTP POST Binding for Authnrequest: Enable this option to allow the SAML logout request to be sent using the HTTP-POST method.
      9. Validate Signatures: Enable this option if you want all the signatures to be validated. If you enable this option, you must also provide the following information:
        1. Validating X509 Certificates: Copy the value of the X509 Certificate value from the View SAML setup instructions page from Okta and provide it for this parameter.
  6. Select Add.

You have successfully added Okta as an IdP via the SAML 2.0 protocol. You can view the newly added IdP under the Identity Providers list page. The next step is to edit the newly created IdP and add mappers.

Add Mappers

Mappers are components that allow you to customize the way user attributes, roles, and group memberships between IdPs and Unifyia. For the newly created IdP select the Edit icon. Go to the Mappers section and follow the succeeding sections to learn more about the three types of mappers - Attribute Importer, Role, and Group that you need to add.

Attribute Importer

You need to add four user attributes mapping between the Okta and the Unifyia platform. The user attributes are username, firstName, lastName, and email. Follow the below steps.

  1. Select + Add Mappers. The Add Identity Mappers page appears. Add the first attribute with the values as seen in the table. Select Save after each user attribute is added.
  2. Repeat the above step until all the user attributes are added.
Name Mapper Type Sync Mode Override Attribute Name User Attribute

First Name

Attribute Importer

Import

firstName

firstName

Last Name

Attribute Importer

Import

lastName

lastName

Email

Attribute Importer

Import

email

email

User Name

Attribute Importer

Import

username

username

Role Mappers

This mapper allows an IdP to map all the IdP uses/groups coming into the Unifyia platform to a selected hardcoded role. You can add multiple hardcoded role mappers if you want the users to be given multiple roles. For each role mapper that you add, you need to select a different role. However, this privilege is at the discretion of the organization. Unifyia supports the below roles.

  • Sponsor
  • Registrar
  • Approver
  • Identity Issuer
  • Security Officer
  • Helpdesk Operator
  • Administrator

Follow the below steps to add hardcoded roles:

  1. For the newly created IdP select the Edit.
  2. Go to the Mappers.
  3. Select + Add Mappers.The Add Identity Mappers page appears.
    1. Name: Enter the name of the mapper you are configuring, for example, role_user.
    2. Mapper Type: From the drop-down list, select Hardcoded Role and select the roles as User.
    3. Select Add.
  4. If you need to add another hardcoded role, for example, Sponsor, then select + Add Mappers.
    1. Name: Enter the name of the mapper you are configuring, for example, role_sponsor.
    2. Mapper Type: From the drop-down list, select Hardcoded Role and select the roles as Sponsor.
    3. Select Add.

As you have configured two roles, each user from the IdP will be assigned two roles while saving to the Unifyia platform database.

Group Mappers

For users from the integrated IdP, you can assign hardcoded groups. If there is no group mapping, all the IdP users will be assigned to the default workflow present in the Unifyia platform and the policies defined in the workflow will apply to all the IdP users. The default workflow also needs to be defined by the organization before adding the IdP.

NOTE
For an organization, you can have only one hardcoded group mapper.

Hardcoded Group Mapper

Enter the following for the hardcoded group mapper:

  1. Name: Enter the name of the mapper you are configuring, for example, Okta Enterprise Group
  2. Mapper Type: Select Hardcoded Group.
  3. Sync Mode Override: Select Import.
  4. Group: Select the group to which the groups coming from Okta must be assigned.
  5. Select Add.

You have now successfully added the mappers and configured the IdP using the SAML v2.0 protocol.

Test Configuration

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

Follow the below steps to log in to the Unifyia platform using Entra ID credentials:

  1. Launch the Unifyia platform.
  2. Select Sign In.
  3. You will notice a button with the user-facing name/logo of the IdP (Okta) on the platform’s sign-in page.
  4. Select it.
  5. The Sign-in page of the Okta application appears.
  6. Enter your credentials.

You will be logged into the Unifyia platform.


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