C3 AI Documentation Home

About IdP Writeback in the C3 Agentic AI Platform

With IdP writeback, C3 AI user management APIs directly update the IdP when you call the APIs in a C3 AI application console. IdP writeback ensures your IdP and C3 AI user management systems remain in sync.

This topic explains how to enable IdP writeback, describes the user management APIs you can use that write back to the IdP, and the IdP writeback flow in the C3 Agentic AI Platform.

Prerequisite

To perform IdP management tasks that write back to the IdP in the C3 Agentic AI Platform, a user must have at least one of the following roles:

  • C3.ClusterAdmin
  • C3.StudioAdmin
  • C3.UserAdmin

Allow non-admin users to perform IdP management tasks

C3OktaWriteBack is an Okta IdP role that lets users perform IdP management tasks in the C3 Agentic AI Platform without requiring further admin-level privileges.

Assign this role to users in the Okta IdP to allow them the following capabilities:

  • User management

    • Create users
    • View and edit user details
    • Edit user group memberships
    • Edit user Okta applications

  • Group management

    • View groups and their details
    • Manage group membership

  • Application management

    • View Okta application details
    • Edit Okta application users or group assignments

Enable IdP writeback

Complete the following steps to enable IdP writeback:

  1. Create an Okta application
  2. Configure the OktaRestApi Type
  3. Create an OpenID Connect (OIDC) application
  4. Configure the OIDC application

1. Create an Okta application

Follow the steps in the Okta documentation at Implement OAuth for Okta with a service app. Apply the following settings:

  1. In the Okta Admin Console, set App Integration sign-in method to API Services
  2. In the Applications > General settings, configure the following:
  • Application type: Service
  • Grant type: Client credentials
  • Proof of possession: Uncheck Require demonstrating proof of posession (DPoP) header in token requests
  • Client authentication: Public key / Private key
  • Public key configuration: Save keys in Okta
  1. Generate a public/private JSON Web Key Set (JWKS) and save the private key.
  2. Grant the following Okta API Scopes:
  • okta.apps.manage
  • okta.apps.read
  • okta.groups.manage
  • okta.groups.read
  • okta.users.manage
  • okta.users.read

2. Configure the OktaRestApi Type

In the C3 AI Console, run the following code to configure the OktaRestApi Type.

Pass the client ID, Okta application URL, private key, and token endpoint. To learn how to provide a key pair using the CryptoPrivateKey Type, see Generate a Cryptographic Key.

JavaScript
// Set the Okta instance details
clientId = "<oktaClientID>";
oktaUrl = '<....>/api/v1';
strFormat = {<PrivateKey>}
tokenOauthEndpoint = "<oktaIntanceID>/ouath2/v1/token";
override = <override>;
var ck = CryptoPrivateKey.fromJwk(strFormat);
// Set the OktaRestApi Type
OktaRestApi.setOAuth(
  oktaUrl,
  RestConfig.OAuth.make({
    clientCredentials: OAuthApplicationCredentials.make({clientId: clientId}),
    tokenEndpoint: tokenOauthEndpoint
  }),
  ck,
  override
);

3. Create an OpenID Connect (OIDC) application

Follow the steps in the Okta Help Center at Create an OIDC Web App in the Okta Admin Console. Apply the following settings:

  1. In the Okta Admin Console, set Sign-in method to OIDC - OpenID Connect.
  2. In the Applications > General settings, configure the following:
  • Client authentication: Client secret
  • Proof Key for Code Exchange (PKCE): Unchecked
  • Grant type: Client credentials, check Authorization code and Refresh Token
  1. In the LOGIN section, add the sign-in redirect URI that contains your C3 AI application URL: https://<applicationUrl>/oidc/login.

4. Configure the OIDC application

In the C3 AI console, configure the OIDC application to enable IdP writeback. Complete Step 5: Configure OIDC in C3 AI application in Integrate OpenID Connect and Okta.

Pass the OIDC Okta application client ID, redirect URI, and Okta application URL.

Then, run the following code to set the configuration:

JavaScript
OidcIdpConfig.forId("<ApplicationURL>").setConfigValue("externalAppId", "<OktaApplicationID>", <ConfigOverride>)
AppUrl.forId("<ApplicationURL>").withIdpConfig(OidcIdpConfig.forId("<ApplicationURL>")).setConfig("CLUSTER")

Next, set the user ID format:

JavaScript
OidcIdpConfig.forId("<ApplicationURL>").setConfigValue("userIdFormat", "LOWERCASE_EMAIL", <ConfigOverride>)

This code sets the user ID format requirement to be lowercase email.

User management APIs that perform IdP writeback

IdP writeback allows the following C3 AI user management APIs to directly write to the IdP.

Okta.createUser

The Okta.createUser API creates a new user in the Okta identity management system. Here is an example of how to call this method:

JavaScript
var user = Okta.createUser({
  username: 'jane.doe@example.com',
  email: 'jane.doe@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  password: 'YourPassword123'
});

Okta.addUserToApp

The Okta.addUserToApp adds the user to the Okta application. Here is an example of how to call this method:

JavaScript
Okta.addUserToApp(`jane.doe@example.com`, `<OktaApplicationID>`)

The <OktaApplicationID> applies to the OidcIdpConfig configuration as the externalAppId.

User.addToGroup

The User.addToGroup API adds a user to a specific group within the C3 Agentic AI Platform. Here is an example of how to call this method:

JavaScript
var user = User.forId('jane.doe@example.com');
var group = UserGroup.forId('group-id');
user.addToGroup(group);

User management flow with IdP writeback

With IdP writeback, user management APIs directly write to the IdP and do not require C3 AI Operations to handle any steps, unless a you create a user without an IdP account. The following diagram describes the IdP writeback flow in the C3 Agentic AI Platform:

sequenceDiagram participant UserAdmin as UserAdmin participant IdP as Identity Provider (IdP) participant App as C3 AI Application UserAdmin->>App: 1. Create a user and add user to Okta application App ->>IdP: 2. Write back to IdP IdP->>IdP: 3. Create a corresponding user in the IdP UserAdmin->>App: 4. Assign user to C3 AI group App->>IdP: 5. User sends authentication request when accessing a C3 AI application URL IdP->>App: 6. Return JSON Web Token (JWT) for authenticated user Note over App: IdP performs authentication only, not authorization
  1. A user with the UserAdmin role creates a user in the C3 AI application with the Okta.createUser API, and adds the user to the Okta application with the Okta.addUserToApp API.
  2. The Okta.createUser and Okta.addUserToApp API writes back to the IdP and the IdP creates a corresponding user in the IdP.
  3. The UserAdmin assigns the user to a C3 AI group with the User.addToGroup API.
  4. The UserAdmin adds the user to a C3 AI group with the User.addToGroup API.
  5. The user sends a request to the IdP to access the C3 AI application.
  6. The IdP returns a JSON Web Token (JWT) for the authenticated user. The IdP performs authentication only, not authorization.

To map the C3 AI application user group to the corresponding IdP group, see Step 6: Set UserGroup mapping in Integrate OpenID Connect and Okta.

Was this page helpful?