About Okta as an IDP

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

ACP 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 ACP 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.

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

1. 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.

Connect Okta IDP

Basic configuration

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

2. In the Add new provider view, select Okta from the list of the predefined IDP templates and click Next.

3. Fill in the form.

   Parameter	Description
   Name	Name for your ACP’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 ACP 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 ACP.

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 Identity Data > Identity 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 ACP.

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 Identity Data > Identity 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 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 Identity Data > Identity 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 Setting up authentication context.

4. Optionally, assign a post-authentication extension to modify your 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

ACP 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 ACP.

Read more

For information on granting and managing ACP consents, see ACP OAuth consents.

Related articles

Having connected and tried out your Okta IDP, check the following resources:

• Configuring claims for ID tokens and access tokens

• Data lineage

• Setting up authentication context

• Connecting to Okta IDP using SAML 2.0