C3 AI Documentation Home

Integrate OpenID Connect and Okta

Okta is an identity and access management service that provides secure user authentication and authorization. It facilitates the management of user identities and ensures that only authenticated and authorized individuals can access applications and data.

A core functionality of Okta is its ability to integrate with OpenID Connect (OIDC), a identity layer on top of the OAuth 2.0 protocol. The primary purpose of integrating Okta APIs with OIDC is to streamline the authentication and authorization process for applications and APIs.

Complete the steps in this topic to integrate Okta APIs with OIDC.

Key terminology

  • Okta: A cloud-based identity and access management service that provides secure user authentication and authorization.

  • OpenID Connect (OIDC): An authentication protocol built on top of OAuth 2.0 that allows clients to verify the identity of an end-user based on the authentication performed by an authorization server, and also to obtain basic profile information about the end-user. Within the OIDC workflow, Okta can act as both the Identity Provider (IdP) or as the Service Provider (SP), depending on your use case.

  • C3.ClusterAdmin: A user role in the C3 Agentic AI Platform required for completing steps on the C3 AI cluster.

  • Application (App) URL: A unique URL for an application. Refer to the AppUrl Type for more information. To define an application URL you must be an C3.AppAdmin (or higher) in the application you are creating and application URL for.

  • OidcIdpConfig: OIDC Identity Provider Configuration, used in the authentication process. Refer to the OidcIdpConfig Type for more information.

  • Auth Token: A token generated in Okta for authentication purposes.

  • ConfigOverride: A configuration setting in the C3 Agentic AI Platform. Refer to the ConfigOverride Type for more information.

Prerequisite

You must be a C3.ClusterAdmin to complete the following steps on the C3 AI cluster.

Step 1: Initialize environment and application

Create and start an environment and application using C3 AI Studio. Refer to the Introduction to C3 AI Studio topic for more information.

Step 2: Create a unique application URL

Note: If you are making application or environment-specific IdP connection then this step is required, otherwise this step is optional.

To integrate an application with Okta using OIDC, developers can register their application with Okta, which includes providing the unique redirect URIs.

A unique application URL, also known as a callback or redirect URI, is crucial for OIDC and Okta integration for several important reasons:

  1. Security assertion: The unique URL is where the identity provider (Okta) sends the authentication response, including tokens and other user information. This URL must be pre-registered with Okta to ensure that it is sending sensitive information to a trusted location, which prevents interception by malicious parties.

  2. Redirection after authentication: After successfully authenticating a user, Okta needs to know where to redirect the user back to within the application. This redirection process is an essential part of the OIDC flow.

  3. Compliance with OIDC Specification: The OIDC specification requires that the redirect URIs be absolute and pre-registered to prevent unauthorized redirection and token theft.

When a user tries to log in, Okta authenticates the user and then redirects back to one of the registered URIs with an authorization code, which the application then exchanges for an ID token and possibly an access token.

Create a unique application URL for the application initialized in Step 1 using the following code snippet:

JavaScript
// Make appUrl and upsert()
AppUrl.make("<your domain>").withEnv("<environment name>").withApp("<app name>").upsert();
// Set authenticationKind field on AppUrl created earlier
AppUrl.setConfigValue("authenticationKind", AuthenticationKind.OIDC)

Be sure to specify the domain, environment name, and app name fields in the application URL before upserting.

Here are examples of hydrated fields:

  • <your domain>: turing.c3.cloud
  • <environment name>: team
  • <app name>: c3
JavaScript
AppUrl.make("turing.c3.cloud").withEnv("team").withApp("c3").upsert();

Step 3: Whitelist application URL

Ensure that the application URL you create in Step 2 is whitelisted by the Operations team. Whitelisting the application URL grants access to the C3 AI Console.

Step 4: Set up OIDC application in Okta

  1. Log into the c3 dev Okta spoke: https://c3dev-admin.okta.com/

  2. Navigate to the Application section and select Create App Integration.

  3. Choose OIDC-OpenID Connect as the sign-in method and select Web Application as the application type. Select Next.

  4. On the General Settings screen:

    • Enter the application name.
    • Select the appropriate grant type.
    • Enter the redirect URI in the format: https://appurl.c3dev.cloud/oidc/login.

  5. In the Assignments section, limit access to specific groups and add the required group name. Create the group if it does not exist.

  6. Save your changes.

  7. After the application is created, navigate to the Sign On tab.

    • Edit the group claim settings to have a group claim filter of groups and a regex of .*.

  8. Copy the Client ID, Client Secret, and the Discovery Endpoint URL (for example, https://c3dev-admin.okta.com/.well-known/openid-configuration) for later use.

Note: The Client Secret is essential for a deeper integration where C3 AI authorized users can manage users, groups, and user-group assignments in Okta.

Step 5: Configure OIDC in C3 AI application

Update the discovery endpoint, client ID, and application URL in your code snippet and run it in the C3 AI Console to configure OIDC on the C3 AI application created in Step 1.

JavaScript
var discoveryEndPoint = "https://c3dev-admin.okta.com/.well-known/openid-configuration"; 
// Redirect uri should be same as configured in Okta application
var uri = "https://<your domain>/oidc/login";  
var client = OidcIdpClient.make({
   clientId:"<clientId>", 
   redirectUri:uri
}); 
var config = OidcIdpConfig.importFromDiscoveryUrl('<your domain>', discoveryEndPoint, client, "form_post");
config.setConfigValue("jitUserCreation", true);
config.setConfigValue("userIdFormat", "EMAIL");
// Set idpWriteback to true to allow c3server to directly modify the user assignments on the IdP
config.setConfigValue("idpWriteback", true);

// For Authorization Code flow:
config.setConfigValue("flowKind", OidcAuthFlowKind.AUTHORIZATION_CODE);
config.setConfigValue("scopes", config.scopes.concat("groups"));
config.setSecretValue("clientSecret", "<client secret from step 4>")

Step 6: Set UserGroup mapping

Map an identity provider to a C3 AI UserGroup (role) in the application using the following code snippet:

JavaScript
UserGroup.forId('<C3UserGroupId>').addIdpGroupForIdp(OidcIdpConfig.forId("<your domain>"), "<IdP group name>")

Step 7: Authenticate and authorize user

  1. Open an incognito browser window and attempt to access the application URL for the C3 AI application. You should be redirected to Okta for authentication.
  2. After authentication, you should be redirected back to the application URL.
  3. Run User.myUser() from the C3 AI Console to verify that the C3 role and IdP group mapping are correctly set.

Step 8: Configure Okta endpoint and authorization

Generate an Okta auth token (Note: only Okta users with the OrgAdmin role can generate an auth token) and configure the Okta endpoint and authorization using the following code snippet:

Text
String oktaUrl = "<https://c3dev.okta.com/api/v1>";
String oktaAuth = "SSWS "+<token>"; 
OktaRestApi.setApiUrlAndAuth(oktaUrl, oktaAuth, ConfigOverride.APP);

You can also configure a service application to perform user management using OAuth 2.0 protocol for REST API requests. To learn how, see Allow calls to REST APIs with OAuth 2.0.

Step 9: Create a new user

Use the Okta.createUser() API to create a new user. You must add this user to both C3 AI and Okta. An activation email is sent to the new user:

JavaScript
var uf = UserFields.builder().email("testoktauser123").familyName("Okta").givenName("Test").build();
Okta.createUser(uf);

In the Okta, set the activate parameter to true to automatically activate user account access after creation. If the activate parameter is not set to true, the user is created in a deactivated state.

Step 10: Add user to group

Add the new user to the <IdP group name> group using Okta.addUserToGroup(<email>, <role>). If the group does not exist in Okta, this API creates a new group.

Step 11: Activate Okta account and access C3 AI application

If you did not set the activate parameter to true in the Okta, you can explicitly activate a user account in Okta.

After the Okta account has been activated, the new user can authenticate and access the C3 AI application. Run User.myUser() in the C3 AI console to confirm the correct C3 AI role and IdP group mapping.

Step 12: Manage user information and deletion

Use Okta#getUserInfo to fetch Okta user details. To remove a user from both C3 AI and Okta, use Okta#removeUser.

Related content

Was this page helpful?