Integrate Okta as an IdP Using OIDC Protocol

This tutorial provides instructions on integrating Okta as an indentity provider for identity federation over the OpenID Connect (OIDC) 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.
  • You must have the Unifyia platform's Sign-in redirect URI and Sign-out redirect URIs.

How to get a Sign-in redirect URI of the platform?

  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, select OpenID Connect v1.0.
  4. Navigate to the IdP Configuration (OIDC v1.0) 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, e.g., okta_idp_oidc
  6. You will notice that the Redirect URL has changed. The given alias name is now added just before /endpoint.
  7. This is the Sign-in redirect URI of the platform. Copy it to a text editor.

How to get a Sign-out redirect URI of the platform?

To generate the sign-out redirect URI, just add /logout_response at the end of the Redirect URL that you have generated in the above section. The format of the URL will be as below:

https://<tenantname>.<domainname>.net:<port>/realms/<tenantname>/broker/<alias>/endpoint/logout_response

Step 1: Add the Unifyia Platform as an Application on Okta

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

  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 OIDC.
  5. For Application Type, select Web Application.
  6. Select Next.
  7. Enter the following information on the New Web App Integration page.
    1. General Settings:
      1. App Integration Name: Enter the name of the application you are adding, e.g., Unifyia Platform
      2. Logo: Upload a logo of your organization or the application.
      3. Grant Type: Select the Client Credentials checkbox.
    2. Sign-in redirect URIs: Enter the redirect URIs, that you obtained from the Unifyia platform authentication server. This will allow Okta to send the authentication response and ID token for the user's sign-in request from this URI. Select + Add URI to add multiple redirect URIs to enable support for multiple tenants.
    3. Sign-out redirect URIs: Enter the redirect URIs for signing out of the application. The user is redirected to this URL after closing the session. Select + Add URI to add more sign-out redirect URIs.
    4. Assignments: Based on your requirement, select one of the following for controlled access. Recommended is to select either option one or two.
      1. Allow everyone in your organization to access: Select this option if you want all of the people in your organization to access this application implicitly.
      2. Limit access to selected groups: Select this option if you want to limit the access of this application to a particular group. After you select this option, from the drop-down list, select the particular group that can access this application.
      3. Skip group assignment for now: Select this option if you want to skip the assignment group or people to this application.
  8. Select Save.
  9. The Web app is created and you will see a new Client ID and Client Secret Copy these values and save them in a notepad. You will require these values during the IdP configuration on the Unifyia platform.
  10. In step 7d, if you've chosen the option Skip group assignment for now, then you must specify the group or people that can access the Unifyia platform application. Go to the Assignments tab.
  11. Select the Assign dropdown. You will find the option to assign users and groups. You can choose to assign the newly added application to specific/all groups or users. Select Done.
  12. You have now successfully added the Unifyia platform as an application in Okta using OIDC.

How do I get Okta metadata?

  1. To configure Okta as an IdP on the Unifyia platform, you will require Okta metadata. On the Okta admin dashboard, you will find your profile details in the top right corner. Select the dropdown. You will find the domain URL. Copy it by selecting the copy icon.
  2. Open a browser and paste this URL. Append .well-known/openid-configuration at the end of this URL. For example, https://utopia.oktapreview.com/.well-known/openid-configuration
  3. The OIDC metadata for OKTA is displayed.
  4. Check the box Pretty-print. The metadata appears well formatted.

You are now all set to configure Okta as an IdP on the Unifyia platform.

Step 2: Configure Okta as an OIDC IdP on the Unifyia platform

This section provides instructions on how to configure Okta as an OIDC IdP on the Unifyia platform.

Prerequisites

  • You need the Client ID and Client Secret that you have saved in step 9 while creating the application on Okta.
  • Ensure to provide the same alias name (e,g., okta_idp_oidc) that you have added to build the Sign-in redirect URL.
  • You will require the following metadata values and URLs of Okta.
    • Client ID (Application ID)
    • Client Secret (Client Credentials)
    • Discovery Endpoint (from the metadata URL)
    • If Discovery Endpoint is not provided, check for the below data in the metadata URL. The required data is
      • Authorization URL
      • Token URL
      • Logout URL
      • User Info URL
      • Issuer
      • JWKS URL

Integration Steps

This section describes the steps to integrate Okta as an IdP on the Unifyia platform.

  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, select OpenID Connect v1.0. The page to configure the identity providers opens. Adding an IdP involves two steps:
    1. General Information: Provide application details and logo to display the application icon to the user.
    2. IdP Configuration (OIDC v1.0): Configuring integrationparameters
  4. Under General Information, enter the following:
    1. App Name (required): Provide a name for the IdP, e.g., OktaIdP_OIDC
    2. Description: Enter a brief description of the identity provider.
    3. Add a logo for the app: Either drag and drop a file or simply click the box to upload a logo for the IdP.
    4. Select Next. You will be directed to the next tab, IdP Configuration (OIDC v1.0), where you'll configure the required OIDC parameters.
  5. Under the IdP Configuration (OIDC v1.0) tab, set the below parameters:
    1. Alias: Provide the same alias name (e.g., okta_idp_oidc) that you have added to build the Sign-in redirect URL.
    2. Domain Name: Provide the domain name of the organization, e.g., utopia.com.
    3. Under OpenID Connect Settings, configure the following:
      1. Use Discovery Endpoint: Enable this option if you want to use the discovery endpoint (OpenID Connect Metadata URL) from Entra ID to acquire values from the metadata URL. If you disable this option, you need to provide the below values manually by referring to the OpenID Connect Metadata Document:
        1. Authorization URL: Provide the authorization_endpoint value from the metadata.
        2. Token URL: Provide the token_endpoint value from the metadata.
        3. Logout URL: Provide the end_session_endpoint value from the metadata.This is optional.
        4. User Info URL: Provide the userinfo_endpoint value from the metadata.This endpoint points to user profile information.
        5. Issuer: Provide the issuer value from the metadata. The server validates issuer claims, in responses from the IdP, against this value. Ensure that you add the Directory (tenant) ID to your Issuer URL post the configuration is complete, e.g., https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
        6. Validate Signatures: Enable this option by moving the slider to the right.
          1. Enable Use JWKS URL by moving the slider to the right.
          2. JWKS URL: Provide the jkws_uri value from the metadata.
        7. Discovery Endpoint: You will find the Discovery endpoint URL in the OpenID Connect Metadata Document that you have opened in a browser. If you provide this value, the
          1. Authorization URL, Token URL, Logout URL, User Info URL, and Issuer values are auto-populated.
          2. Validate Signatures option acquires the values from the metadata URL and the JWKS URLvalue is auto-populated.
        8. In the last section, provide client data.
          1. Client Authentication: Choose Client secret sent as basic auth. Select this option if the Client Secret is to be sent as a part of the basic authentication for the APIs.
          2. Client ID: You have copied the Client ID value to a text editor after completing the configuration of the Unifyia platform as an application on the Okta application. Provide that value here.
          3. Client Secret: Provide the client secret from the above-mentioned text editor.
          4. Client assertion signature algorithm: Select HS256. Currently, the platform supports the HS256 signature algorithm to create a JWT assertion.
  6. Pass Login Hint: Disable this option.
  7. Select Add.

You have successfully added Okta as an IdP. You can view the newly added IdP under the Identity Providers list page.

Add Mappers

Mappers are components that allow you to customize the way user attributes, roles, and group memberships are mapped between IdPs and Unifyia.

  1. For the newly created IdP select the Edit.
  2. Go to the Mappers.
  3. Select + Add Mappers. The Add Identity Mappers page appears.
  4. You need to add two mappers - Role and Group. Refer to the below sections for more information.

Role Mapper

This mapper allows an IdP to map all the IdP users/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, e.g., 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, e.g., role_sponsor.
    2. Mapper Type: From the drop-down list, select Hardcoded Role and select the roles as Sponsor.
    3. Select Add.
  5. As you have configured two roles, each user from the IdP will be assigned two roles while saving to the Unifyia platform database.

Group Mapper

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, e.g., 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. This completes the configuration of the Okta as a SAML IdP.

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 Okta 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. You will be logged into the Unifyia platform.

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