Prerequisites for Integration with Identity Providers

The C3 Agentic AI Platform supports Identity Provider (IdP) integration. This means customers can integrate with any IdP of their choice or use the default IdP provided by C3 AI, Okta and OpenID Connect (OIDC). Users of the platform can authenticate and manage identities using their existing IdP systems, facilitating secure access and identity verification across their applications. This capability is essential for organizations that need to maintain consistent security policies and user management practices across different systems, including those built on or interacting with the C3 Agentic AI Platform.

This topic outlines the steps of integrating IdPs such as Google, Microsoft Entra ID, or Okta with the C3 Agentic AI Platform, ensuring a secure and efficient setup for your applications.

Copy link to this section

Key terminology

Before discussing the integration steps, let's clarify the roles involved in the process:

• ACS (Access Control Service): ACS is a security component that provides authentication and authorization services. It can be used to manage access to resources within a system, ensuring that only authenticated and authorized users or systems can access certain data or functionalities. The ACS plays a crucial role in security by managing identities, permissions, and access policies.

• ACS URL: This is the URL or endpoint for the Access Control Service. It's where authentication requests are sent and processed. The URL must be secured and correctly configured to ensure that authentication processes are both secure and efficient.

• Application URL: An application URL refers specifically to the URLs used to access various applications, services, or interfaces provided by the C3 Agentic AI Platform. The application URL is specific to a single application or environment within a cluster.

• Canonical URL: The canonical URL serves as the base URL from which all C3 AI applications and services are accessible, ensuring a uniform entry point and consistency across the C3 Agentic AI Platform.

• C3 AI Administrator (C3 AI Admin): This person manages the C3 Agentic AI Platform side of the setup, including application configurations and security settings.

• C3 AI Delivery Services: This team leads the integration, coordinating between all parties to ensure a smooth setup.

• DNS Administrator: Responsible for managing Domain Name System (DNS) records, this person can be either a C3 AI employee or the customer, depending on the setup.

• IdP Administrator (IdP Admin): This individual manages the IdP configuration on the IdP side. The IdP Admin can be a C3 AI employee or the customer.

Copy link to this section

Step 1: Initial coordination and information gathering

The integration process begins with C3 AI Delivery Services engaging in a critical dialogue with the IdP Admin. The purpose of this conversation is to collect essential information that defines the technical pathway of the integration.

To ensure a logical and efficient integration process, address the following topics below:

1. IdP and DNS ownership.
2. Authentication protocol (SAML vs OIDC)
3. Canonical or Application URL
4. Decide on the ACS URL.

Copy link to this section

IdP and DNS

Determining the management of IdP and DNS: It's essential to decide whether to use the customer’s IdP and DNS or C3 AI's default (Okta OIDC). This decision is critical for the strategic direction of the integration.

• Default Configuration: By default, the IdP uses a C3 AI managed Okta OIDC, and C3 AI manages the DNS.

• Customer Managed Option: If the cluster is hosted in a customer-managed cloud, the customer needs to manage the DNS.

NOTE: Additionally, C3 AI Delivery Services must communicate with the DNS Administrator to create an ACS URL DNS record, ensuring the correct DNS resolution is in place for the integration.

Copy link to this section

Identity Provider (IdP) configuration

• Evaluate IdP Options: Decide whether to utilize the C3 AI managed IdP service or the customer IdP for authentication and authorization.

• Select Default IdP: If no specific preference is indicated, opt for the C3 AI managed Okta OIDC as the default IdP. This is a secure and standardized option for managing user identities.

Copy link to this section

Domain Name System (DNS) management

• Determine DNS Management Responsibility: Choose who manages the DNS - C3 AI or the customer. By default, DNS management is handled by C3 AI if the customer opts for C3 AI management.

• Consider Hosting Environment: If the cluster is hosted in a customer managed cloud environment, then the customer must also manage the DNS settings.

• SSL Certificate Provisioning: In cases where the customer manages the DNS, the customer must also provide an SSL certificate to secure communications to and from the C3 Agentic AI Platform.

Copy link to this section

SSL certificate recommendations

• Opt for a Wildcard Certificate: The customer should provide a wildcard SSL certificate. A wildcard certificate ensures that both your main domain and an unlimited number of its subdomains are secured under a single certificate, facilitating easier management and implementation.

NOTE: If a wildcard is not provided, C3 AI Services needs to identify all App URLs for the cluster and request that DNS Admin add the App URLs as SANs in addition to the canonical on the certificate

Copy link to this section

SAML vs OIDC

Will you use SAML or OIDC? These are the two main protocols for web-based single sign-on (SSO) systems. The choice between SAML and OIDC impacts the configuration steps.

If there is no preference, the default authentication protocol is OIDC.

Copy link to this section

Canonical URL vs application URL

In the context of integrating identity providers (IdPs) with the C3 Agentic AI Platform, the difference between canonical URLs and application-specific (app) URLs is crucial for setting up the Assertion Consumer Service (ACS) URL, which is central to the SAML authentication process.

Copy link to this section

Canonical URL

The canonical URL serves as the base URL for accessing all applications and services on the C3 Agentic AI Platform. It provides a uniform entry point and ensures consistency across different services within the platform. For example, a canonical URL could be structured like https://mycluster.domain.com/c3/c3, which indicates a general access point to the platform's ecosystem.

You can use the canonical URL as a foundation for setting up various service endpoints, including the ACS URL for SAML authentication.

In a SAML setup, the ACS URL built on a canonical URL might look something like https://mycluster.domain.com/c3/c3/saml/login.

Here:

• https is the protocol ensuring secure communication.
• mycluster.domain.com is the domain where the C3 Agentic AI Platform is hosted.
• c3/c3 is a path within the platform indicating a specific or general access point.
• saml/login is the endpoint where the SAML assertion for user authentication is processed.

Copy link to this section

Application URL

Application URLs, on the other hand, are more specific and you typically use an application URL to access individual applications within the C3 Agentic AI Platform. They might not include additional path segments that indicate broader platform access (like the c3/c3 in the canonical URL).

An application URL can be as straight-forward as https://mycluster.domain.com, directly leading to a specific application hosted on the platform.

When used in an ACS setup for SAML, an app-specific ACS URL can be simpler, such as https://mycluster.domain.com/saml/login.

This structure includes:

• https for secure communication.
• mycluster.domain.com as the domain.
• saml/login as the direct endpoint for SAML authentication, without additional path segments indicating broader platform access.

Copy link to this section

Relevance in ACS setup

The choice between using a canonical URL versus an application URL for the ACS setup affects how authentication traffic is routed within the C3 Agentic AI Platform.

It determines:

• Scope of Access: A canonical URL in the ACS setup implies a broader scope of access, potentially across multiple services or applications within the platform. An application URL targets a specific application, which might be necessary when different apps require distinct authentication configurations.

• Configuration Consistency: Using a canonical URL can simplify the management of authentication configurations across the platform, as it centralizes the entry point for SAML assertions. Conversely, application URLs might necessitate more granular configuration if different apps have unique authentication needs.

• Security and Control: Depending on the organizational and security requirements, it might be preferable to have more controlled access using application URLs, especially if different applications on the platform have different security levels or user bases.

The choice between using a canonical or an application URL for the ACS URL setup hinges on the specific needs of the C3 Agentic AI Platform’s deployment, including considerations for security, management simplicity, and the specific architecture of the platform and its applications.

Is an app URL or canonical URL being used? Identifying the type of URL in use helps tailor the integration process to the specific needs of the application.

There must be a canonical URL for every new cluster. Services and the customer can optionally request additional App URLs in addition to the canonical URL.

Copy link to this section

ACS URL

What is the Assertion Consumer Service (ACS) URL? The Assertion Consumer Service (ACS) URL is a key endpoint where the IdP sends its authentication assertions. An ACS URL is a crucial component in the SAML protocol used for single sign-on (SSO) services.

In SAML SSO implementations, the ACS URL is the endpoint at which the SAML assertion is received from the IdP. This URL is where the service provider (like the C3 Agentic AI Platform) receives the SAML response containing the authentication assertion after a user attempts to log in. The ACS URL is configured within the service provider's settings and must be precisely matched by the IdP's configuration to ensure secure communication and user authentication.

NOTE: The ACS URL is essentially either a canonical URL or an app-specific URL that includes a path for handling the SAML login authentication protocol.

To clarify in terms of URL structure:

For example, if the canonical or app-specific URL is https://mycluster.domain.com, the ACS URL would be structured as follows:

• Canonical ACS URL: https://mycluster.domain.com/c3/c3/saml/login
• App-Specific ACS URL: https://mycluster.domain.com/saml/login

In these examples:

• https is the scheme, ensuring secure communication.
• mycluster.domain.com represents the domain where the C3 Agentic AI Platform is hosted.
• c3/c3 specifies the particular path within the platform, indicating either a general access point or a specific application.
• saml/login is the endpoint where the SAML assertion is processed, indicating the use of the SAML protocol for authentication.

This structure ensures that the authentication assertion from the IdP is directed to the correct location within the service provider's architecture, thus facilitating secure and effective user authentication.

Copy link to this section

Example URLs

Provided are examples to illustrate the typical structure and use cases for both Canonical and Application URLs within the context of OIDC and SAML, along with examples for specific application access.

Canonical OIDC URL Example: https://mycluster.domain.com/c3/c3/oidc/login

• mycluster.domain.com: This is the hostname or domain name, representing the address where the C3 Agentic AI Platform is hosted. It typically indicates the specific cluster or environment of the platform.

• c3/c3: This portion represents a namespace or organizational path within the platform.

• oidc/login: This is the specific path for the OpenID Connect (OIDC) login operation. OIDC is a simple identity layer on top of the OAuth 2.0 protocol, and you use this URL to initiate a login flow using OIDC for authentication.

Canonical SAML URL Example: https://mycluster.domain.com/c3/c3/saml/login

• The components mycluster.domain.com, and c3/c3 have the same meanings as described above.

• saml/login: This part of the URL is dedicated to the Security Assertion Markup Language (SAML) login process. SAML is a standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. This URL initiates a login flow that uses SAML for authentication.

App URL Example: https://mycluster.domain.com/

• mycluster.domain.com retains its meanings as the domain name.

The path above directly leads to a specific application hosted on the C3 Agentic AI Platform. Unlike the canonical URLs, which include c3/c3 indicating a broader access path or organizational structure, the App URL accesses only one particular application.

The omission of c3/c3 simplifies the URL and makes it specific to accessing that app directly.

Each of these URLs serves a different purpose within the C3 Agentic AI Platform's ecosystem, facilitating secure and structured access to its various features and applications, whether for authentication processes or direct application access.

Note: When using a canonical URL (such as, https://mycluster.domain.com/c3/c3/oidc/login), it is essential to set the OIDC configurations at the ConfigOverride.CLUSTER level. This configuration step ensures that the URL is applied for all authorizations across any new applications or environments created with the cluster. The setup requires only one OIDC entry on the customer's side and one OIDC entry on the C3 AI side, streamlining the integration process and ensuring consistent authentication across the platform.

// Specify the discovery URL for the OIDC provider, where the OIDC configuration can be retrieved
var discoveryEndPoint = "https://<domain name>/.well-known/openid-configuration";
// Define the redirect URI, the endpoint
var uri = "https://mycluster.domain.com/c3/c3/oidc/login";
// Create the OIDC client
var client = OidcIdpClient.make({
  clientId: "mycluster.domain.com",
  redirectUri: uri
});
// The "true" parameter in the following command enables auto-importing certificates. Set to false if that feature should not be enabled.
// Import the OIDC configuration from the discovery URL, notice it is set at the cluster level
var config = OidcIdpConfig.importFromDiscoveryUrl("mycluster.c3.ai", discoveryEndPoint,client, "form_post", true, ConfigOverride.CLUSTER);
OidcIdpConfig.forId("mycluster.domain.com").setConfigValue("trustedApplicationHosts", C3.Array.ofStr("mycluster.c3.ai"), ConfigOverride.CLUSTER);
OidcIdpConfig.forId("mycluster.domain.com").setConfigValue("jitUserCreation", true, ConfigOverride.CLUSTER);
OidcIdpConfig.forId("mycluster.c3.ai").setConfigValue("scopes", Array.of("openid", "email", "profile", "groups"), ConfigOverride.CLUSTER);
UserGroup.forId("C3.ClusterAdmin").addIdpGroupForIdp(config, "mycluster.c3.ai/C3.ClusterAdmin"); 
OidcIdpConfig.forId("mycluster.c3.ai").setConfigValue("userIdFormat", "EMAIL", ConfigOverride.CLUSTER);

Copy link to this section

Step 2: IdP setup

Additional documentation you should reference when creating an application, working with specific identity providers, and authentication protocols can be found in the topics below:

• OpenID Connect Authentication
• OpenID Connect and Okta integration
• Authenticate Using SAML
• Google IdP Integration
• Okta Integration
• Microsoft Entra ID Integration

Copy link to this section

Create SSO application (OIDC/SAML)

After gathering the necessary information, the IdP Admin must configure the IdP with the details specific to the customer's application and the C3 Agentic AI Platform. This step is crucial for setting up the SSO application to communicate effectively with the C3 Agentic AI Platform, with a focus on the determined ACS URL.

This involves:

Copy link to this section

Passing the email attribute

• Email Attribute: This is a piece of identifying information that is passes from the IdP to the C3 Agentic AI Platform during the authentication process. It uniquely identifies a user by their email address. Configuring the SSO application to pass the email attribute is crucial for user identification and for mapping the user to their account on the C3 AI Platform.

Copy link to this section

Passing the group attribute

• Group Attribute: Similar to the email attribute, the group attribute is a piece of information provided by the IdP that identifies the user group(s) to which a user belongs. This attribute is vital for role-based access control (RBAC) within the C3 Agentic AI Platform, allowing for the automatic assignment of permissions based on the user's group memberships.

Copy link to this section

Create IdP group assignments

Creating specific IdP group assignments is essential for defining access levels within the C3 Agentic AI Platform. At a minimum, the following groups should be created:

• Cluster Admin - C3 AI Ops (not C3 AI Delivery Services): This group is assigned to operational administrators who manage the C3 AI Platform at a cluster level, including infrastructure and critical system components.

• Studio Admin - Cluster Owners: Members of this group have administrative rights within the C3 AI Studio, typically assigned to those responsible for overseeing the development and deployment of applications on the platform.

• Studio User - Basic Users: This group includes users with basic access to the C3 AI Studio, allowing them to use applications and perform tasks as per their role's requirements. A Studio User can only view their applications.

Copy link to this section

Create IdP group assignments

Creating specific IdP group assignments is essential for defining access levels within the C3 Agentic AI Platform. At a minimum, the following groups should be created:

• Cluster Admin - C3 AI Ops (not C3 AI Delivery Services): This group is assigned to operational administrators who manage the C3 AI Platform at a cluster level, including infrastructure and critical system components.

• Studio Admin - Cluster Owners: Members of this group have administrative rights within the C3 AI Studio, typically assigned to those responsible for overseeing the development and deployment of applications on the platform.

• Studio User - Basic Users: This group includes users with basic access to the C3 AI Studio, allowing them to use applications and perform tasks as per their role's requirements. A Studio User can only view their applications.

• Filtering with relevantGroups: If the relevantGroups field is set, it filters the IdpAssignedGroups to include only groups that are part of the relevantGroups.

• Accepting All Groups: If the relevantGroups field is not set, all groups received from the IdP are accepted.

More information about roles can be found in the Built-in C3 Agentic AI Platform Roles

Copy link to this section

Provide SSO app information to C3 AI

After setting up the SSO application, the next step is to provide the C3 AI team with necessary application information, which varies based on whether you use the SAML or OIDC protocol:

Copy link to this section

SAML app metadata (SAML)

• SAML App Metadata: This is an XML document that contains settings and configurations necessary for SAML SSO, such as entity IDs, assertion consumer service (ACS) URLs, and certificate information. Sharing this metadata with the C3 AI team enables them to configure the C3 Agentic AI Platform to trust and accept SAML assertions from the IdP.

Copy link to this section

OIDC specific considerations

For integrations using OIDC, the IdP Admin needs to ensure the following specific information is provided to the C3 AI team:

• Entity ID: A unique identifier for the SSO application within the OIDC framework. This ID is essential for distinguishing the application in the authentication process.

• Discovery URL: The URL where the OIDC configuration information of the IdP can be retrieved. This URL is crucial for the C3 Agentic AI Platform to automatically fetch and understand the IdP's configuration, facilitating a streamlined setup process.

Providing the C3 AI team with this OIDC-specific information, alongside the SAML app metadata for SAML-based integrations, is critical for enabling the C3 Agentic AI Platform to properly interact with the IdP. This ensures that authentication and authorization processes are handled efficiently and securely, aligning with best practices for web-based SSO systems.

Copy link to this section

IdP group names (both OIDC and SAML)

• IdP Group Names: Providing the names of the IdP groups (for example, Cluster Admin, Studio Admin, Studio User) is crucial for mapping these groups to corresponding roles and permissions within the C3 Agentic AI Platform. This ensures that users are granted access based on their group memberships, aligning with the principle of least privilege.

This phase of the IdP Integration process involves critical configuration steps within the IdP to ensure secure and streamlined access to the C3 Agentic AI Platform. By meticulously setting up the SSO application to pass the necessary attributes and creating clear group assignments, you pave the way for efficient user management and access control. Providing the C3 AI team with detailed SSO application information, including SAML app metadata and IdP group names, completes the integration, allowing for a seamless authentication experience.

Copy link to this section

Step 3: Integrating with the C3 Agentic AI Platform

With the IdP configured, the next steps now shifts to the C3 AI Administrator to finalize the integration of the IdP with the C3 Agentic AI Platform. This phase involves leveraging the metadata provided by the IdP Admin in Step 2 and completing crucial configuration tasks within the C3 AI environment.

Let's explore these steps in detail.

Copy link to this section

Use the metadata for configuration

The C3 AI Admin starts by using the metadata obtained from the IdP Admin. This metadata is crucial for configuring the SSO application on the C3 Agentic AI Platform.

The primary configurations include:

Copy link to this section

The canonical or app URL

• Canonical/App URL Configuration: This involves specifying the application's URL within the C3 Agentic AI Platform settings. The Canonical URL is the official URL for users to access the application, ensuring consistency and security in how the application is reached. This URL must match one of the URLs provided in the IdP metadata to ensure seamless communication and authentication flow between the IdP and the C3 Agentic AI Platform.

Copy link to this section

SAML or OIDC configuration

• SAML Configuration: If using SAML for SSO, the C3 AI Admin configures the C3 Agentic AI Platform to understand and process SAML assertions. This includes setting up the Assertion Consumer Service (ACS) URL (where the SAML assertions are sent), the entity ID, and the SAML certificates, all which are part of the metadata provided.

• OIDC Configuration: For OpenID Connect, the configuration focuses on setting up the client ID, client secret, and the redirect URIs. These elements enable the platform to authenticate users using OIDC, exchanging tokens that grant access.

Copy link to this section

Create role mappings

Once the basic SSO setup is configured, the next crucial step involves role mapping based on the IdP groups. Role mapping is the process of assigning specific roles and permissions on the C3 Agentic AI Platform to the user groups defined by the IdP.

This ensures that:

• Cluster Admin - C3 AI Ops are given roles that allow them to manage and monitor the platform at a high level, including access to infrastructure and system settings.

• Studio Admin - Cluster Owners receive administrative capabilities within the C3 AI Studio, enabling them to manage applications, deployments, and other users within their purview.

• Studio User - Basic Users are granted access to use applications and perform tasks according to their role's limitations, ensuring operational security and efficiency.

Copy link to this section

DNS configuration for ACS URL

The final technical step involves the DNS configuration for the Assertion Consumer Service (ACS) URL. The DNS Administrator manages this step. This step ensures that the domain name system (DNS) correctly resolves the ACS URL used in SAML assertions. It's a critical setup that allows the IdP's responses to be correctly directed to the C3 AI Platform, ensuring that authentication responses from the IdP reach the platform without issues. The DNS configuration involves:

• Creating an A-record or CNAME record in the DNS that points to the correct IP address or hostname of the C3 AI Platform.

• Ensuring that the ACS URL's DNS matches the one provided during the SSO application setup in the C3 AI environment.

This phase of the IdP integration process is pivotal, as it solidifies the SSO application's operational readiness within the C3 Agentic AI Platform.