Skip to main content

Set Up Okta for Authentication - OIDC

Learn how to configure Okta and SecureAuth to enable your users to sign in using Okta IDP.

Integration Pattern

In case of OIDC integration, SecureAuth integrates with Okta in a specific way. Instead of using a single application in Okta to authenticate the users, SecureAuth creates an application in Okta for each application registered in SecureAuth. This allows to keep the per-application rules configuration in Okta while providing the seamless experience for clients using SecureAuth. To make this integration pattern work, SecureAuth first needs a service application in Okta with application management rights to create those applications on SecureAuth's behalf.

You can integrate SecureAuth with Okta IDP using either OIDC or SAML, as explained in the below instructions:

About Okta as IDP

Okta is natively supported by SecureAuth as an OIDC Identity Provider, which means that it has a dedicated connection template in SecureAuth for your convenience. Okta applications implement the OIDC protocol, providing the proof of user authentication to SecureAuth within an ID Token and Access Token.

SecureAuth uses the private_key_jwt authentication flow to authenticate with Okta. For more information about this flow, read Client authentication using private_key_jwt.

Okta and SAML

Okta applications can also use the SAML protocol, but this integration is not natively supported by SecureAuth yet. If necessary, you can use the generic SAML connector to bind Okta apps via SAML. For more information, read Connecting to Okta IDP using SAML 2.0.

Connect Okta with OIDC

Prerequisites

  • You have an Okta developer account.

  • You have a service application registered in Okta. For help, follow Okta documentation for creating a service app.

    Note

    Creating an application in Okta with access to Okta application management APIs requires private_key_jwt as the authentication method. To use this method, a public/private key pair is needed. When following the above instruction, make sure to create a PEM private key from the key pair using any tool of your choice.

Grant Scopes for Okta App

  • In the Okta developer portal, go to Applications -> YOUR_APP -> Okta API Scopes and grant the following scopes:

    • okta.apps.manage

    • okta.groups.read

    Note

    Keep your Okta application page open in your browser so that you can check its details when needed in the subsequent steps.

Basic Configuration

  1. In your workspace landing page, select Authentication > Providers > Create Connection to add a new connection.

  2. In the Create Connection page, select Okta from the list of the predefined IDP templates and click Next.

  3. Fill in the form.

    Parameter

    Description

    Name

    Name for your SecureAuth's Okta connection. This name allows users to identify the IDP they need to authenticate with.

    Domain

    Okta domain where the service app is registered. Do not include the protocol - the domain format must be similar to dev-136121869.okta.com.

    Client ID

    Client ID of the OAuth application registered in Okta

    Client private key

    Client private key used by SecureAuth to sign the JWT. Must be in PEM format.

  4. Optionally, enable Authentication context caching.

    Tip

    You can enable the authentication context caching if you wish to store the user's authentication context locally. If you do, specify the cache Time To Live as well. Learn more by reading Stateful authorization with SecureAuth.

  5. Save your changes. You can now configure the advanced settings for your IDP or try it out right away.

Advanced Configuration

Advanced settings contain optional features which may be necessary to use in specific cases. To configure your new IDP advanced settings

  1. From the Authentication > Providers > YOUR_IDENTITY_PROVIDER > Configuration page, select Advanced settings at the bottom.

  2. In the Scopes field, add additional scopes to be requested when authenticating to the IDP (by default openid, email, and profile scopes are requested).

    Note

    Since multiple clients can use the same IDP for user authentication, you may need to further restrict specific client's ability to request a given scope. For more information, read about Configuring applications in SecureAuth.

  3. In the Authentication Method Reference you can select an authentication method to be written into the amr object returned by the IDP. The amr object is written if it doesn't exist. If it exists, its values are replaced with the selected item.

    Tip

    You can also use an extension script to modify amr values. If you do, keep in mind that the script is executed after the amr injection from this field, so the values injected by the script are final.

  4. Enable the Use Org authorization server option to use Okta's Org Authorization Server. The default custom authorization server is used otherwise. To use your own Okta server, enter the server ID in the Authorization server ID field. For more information, read Okta documentation on authorization servers.

  5. Enable the Get user info option to get the user's group membership information.

  6. Select Save.

Add custom OIDC IDP attributes

If your IDP returns custom claims outside of the standard OIDC scope, make sure to add them to the IDP connector so that they can be recognized and mapped to the authentication context. Some IDPs (for example Cognito) may require you to set custom attribute permissions first.

  1. Go to Authentication > Providers and select an IDP from the list.

  2. Open the Attributes page. A standard list of OIDC attributes returned by this IDP appears.

  3. Select Add attribute.

  4. In Source, select the data source for the custom attribute

    Source

    Description

    Access token

    Get data from the access token received from the IDP

    ID token

    Get data from the ID token received from the IDP

    User info

    Get data data returned by the OIDC user info endpoint (note that this must be explicitly enabled on the IDP connector)

  5. Fill in the rest of the form.

    Option

    Description

    Claim name

    Name of your custom attribute matching the incoming IDP claim

    Display name

    User-friendly name for the custom attribute

    Data type

    Data type matching that of the incoming IDP claim

    Claim names with a . character

    If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

  6. Save your changes and proceed to mapping the attributes to the authentication context.

Map IDP Attributes to Authentication Context

If you've added custom attributes for an IDP, you need to make sure they are mapped to the SecureAuth authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

  1. Go to Authentication > Providers and select an IDP from the list.

  2. Open the Mappings page. A standard attribute mapping for this IDP appears.

  3. Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

    Note

    If you need to create new authentication context attributes, read the Managing Authentication Context.

  4. Optionally, you can enrich authentication context before issuing the token to the client. Attributes returned by the script do not need to be separately mapped to the authentication context.

  5. Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Test your IDP

Prerequisites

  • Your IDP is enabled for user authentication.

  • Demo workspace is created with the Demo Portal connected.

Test

  1. Open the Demo Portal (Data lineage -> Demo Portal -> Launch).

  2. Select LOGIN TO DEMO APP.

  3. Select your configured IDP and, next, authenticate in IDP.

    Result: SecureAuth displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from Okta is delivered through the access token and the ID token generated by SecureAuth.

    token_issued.png

Note

For information on granting and managing SecureAuth consents, see Consents.

In this section: