Authentication Using SAML

Use Security Assertion Markup Language (SAML) to enable a single sign-on (SSO) experience for users of your C3 AI application(s). The sign-on workflow differs depending upon whether the process is initiated by your Identity Provider (IdP), for example Microsoft Entra ID, or the Service Provider (SP), the C3 Agentic AI Platform.

The C3 Agentic AI Platform supports both Service Provider-Initiated (SP-initiated) and Identity Provider-Initiated (IdP-initiated) SSO.

Copy link to this section

Service Provider-Initiated SSO

SP-initiated SSO involves the C3 Agentic AI Platform creating a SAML request and redirecting both the user and the request to the identity provider. After the identity provider has validated the request, and the user has authenticated at the identity provider, the user is redirected back to the C3 Agentic AI Platform along with a SAML response and assertion issued by the identity provider. The C3 Agentic AI Platform validates the response and grants the user access to the C3 Agentic AI Platform.

Copy link to this section

Configuring SP-Initiated SSO

The below steps provide an overview of the process required to enable SAML 2.0 integration. Details for each step may vary based upon your IdP.

1. Generate the SAML single sign-on descriptor for your environment. The SP SSO descriptor describes service provider configuration and describes the Assertion Consumer Service (ACS) of the service provider. The ACS URL directs the IdP where to send its SAML Response after authenticating a user. To generate the SP SSO descriptor:

var spec = SpSsoDescriptorSpec.make({ acsUrl : "https://<AppUrl>/c3/c3/saml/login" });
var resp = Saml.generateSpSsoDescriptor(spec);

Use the ACS URL based on your SAML configuration level:

• For cluster-level SAML configuration, use https://<AppUrl>/c3/c3/saml/login.
• For environment-level SAML configuration, use https://<AppUrl>/c3/saml/login.
• For application-level configuration, use https://<AppUrl>/saml/login.

The code snippets in this topic use cluster-level SAML configuration as an example.

Refer to the function Saml#generateSpSsoDescriptor for more information.

The response of Saml.generateSpSsoDescriptor can be an XML document that should be provided to your IdP administrator to register the C3 AI Application with the IdP. The SAML SSO descriptor can look like:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="<AppUrl>">
   <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
      ...

2. Using the information provided in the SAML SP SSO descriptor, register the C3 AI Application with the IdP. Identity providers such as Microsoft Entra ID can import the descriptor when creating the application.

3. Generate your identity provider's SAML metadata in an XML file, then upload the XML file to the C3 Agentic AI Platform. C3 AI Platform's SAML registration requires this XML file. Upload the file in C3 AI Console. Select Tools > Load File, choose the file, set the destination to File System, and select the default mount (/).

4. Register the identity provider with the C3 Agentic AI Platform using the provider's SAML metadata file.

// The file uploaded to the C3 Agentic AI Platform in step 3.  The location will vary.
var samlFile = FileSystem.listFiles(FileSystem.mountUrl('/')).files[0];

var acsUrl = "https://<AppUrl>/c3/c3/saml/login";
// Fully qualified domain name
var fqdn = "<AppUrl>";
var env = "<c3env>";
var app = "<c3app>";
var compressRequest = false;
var hasExternalDns = true;

// register SAML provider metadata with the C3 Agentic AI Platform
var resp = Saml.generateSpSsoArtifacts(samlFile, acsUrl, fqdn, env, app, compressRequest, hasExternalDns);

Refer to Saml for a description of the parameters passed to the generateSpSsoArtifacts method.

5. After the identity provider is registered with the C3 Agentic AI Platform, configure a default access group or map groups in the identity provider to C3 AI User Groups.

6. To configure a default access group, update the SAML configuration as shown below.

var config = SamlIdpConfig.make(fqdn).getConfig();
config.setConfigValue("<default group id>", "<id of user group>");

7. How to map the identity provider to a C3 AI User Group, run the example below for each group.

var samlConfig = SamlIdpConfig.forId("<appUrl>");
var idpGroup = "<idp group name>";
UserGroup.forId("<id of user group>").addIdpGroupForIdp(samlConfig, idpGroup);

The C3 Agentic AI Platform offers the ability to configure custom mappings of keys from an IdP:

// Creating a SAML Configuration Object:
var samlConfig = SamlIdpConfig.forId("<appUrl>");
// Ask the IdP Administrator what the Single sign-on is in the IdP portal ex:Azure
//
//                         OR 
//
// Log in once and determine what keys they are sending by:
// Decode the SAMLResponse using https://samltool.io/ to determine how the IDP is sending the below information
//
// Below is an example for defining attribute keys:
var ak = {
   groups:"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
   email: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
   firstName: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
   lastName: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
};
 
var configLevel = "<appUrl>";
samlConfig.setConfigValue("settings.attributeKeys", ak, configLevel);

The variable ak maps the attribute keys from the IdP's SAML response to the corresponding C3 AI attributes. These keys typically represent user group memberships, email addresses, and names.

This mapping ensures that the C3 Agentic AI Platform correctly interprets the user information contained in the SAML response, facilitating proper user authentication and authorization.

By customizing these mappings, you can adapt the C3 Agentic AI Platform to work with different IdPs and their unique attribute configurations, ensuring a seamless single sign-on (SSO) experience for users.

Copy link to this section

Identity Provider Initiated SSO

IdP-initiated SSO involves a user authenticating with the Identity Provider (IdP) and being redirected to the C3 AI Platform along with a SAML response and assertion. The C3 Agentic AI Platform is expected to accept the response and grant the user access to the C3 AI Application.

Copy link to this section

Configuring IdP-Initiated SSO

1. Generate the SAML single sign-on descriptor for your environment. The SAML SSO descriptor describes service provider configuration and the Assertion Consumer Service (ACS) of the service provider. The ACS URL directs the IdP where to send its SAML Response after authenticating a user. To generate the SSO descriptor for your application, navigate to Console for your application and run the following:

var spec = SpSsoDescriptorSpec.make({ "acsUrl" : acsUrl });
var resp = Saml.generateSpSsoDescriptor(spec);

The response of Saml.generateSpSsoDescriptor can be an XML document that should be provided to your IdP administrator to register the C3 AI Application with the IdP. The SAML SSO descriptor can look like:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="<AppUrl>">
   <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
      ...

2. Using the information provided in the SAML SSO descriptor, register the C3 AI Application with the IdP. Identity providers such as Microsoft Entra ID can import the descriptor when creating the application. Consult your identity provider's documentation on how to register an application.

3. Generate your identity provider’s SAML metadata in an XML file and upload the XML file to the C3 Agentic AI Platform. This file can be required to complete the C3 Agentic AI Platform's SAML registration. Upload the file in the C3 AI Console. Select Tools > Load File, choose the file, set the destination to File System, and select the default mount (/).

4. Register the identity provider with the C3 Agentic AI Platform using the identity provider's SAML metadata file.

// The file uploaded to the C3 Agentic AI Platform in step 3.  The location will vary.
var samlFile = FileSystem.listFiles(FileSystem.mountUrl('/')).files[0];

var acsUrl = "https://<AppUrl>/c3/c3/saml/login";
var appUrl = "<AppUrl>";
var env = "<c3env>";
var app = "<c3app>";

// register SAML provider metadata with the C3 Agentic AI Platform
var resp = Saml.generateIdpSsoArtifacts(samlFile, appUrl, env, app);

After the identity provider is registered with the C3 Agentic AI Platform, configure a default access group or map groups in the identity provider to C3 AI User Groups.

5. To configure a default access group, update the SAML configuration as shown below.

var config = SamlIdpConfig.make(fqdn).getConfig();
config.setConfigValue("defaultGroupId", <id of user group>); 

6. To map an identity provider to a C3 AI User Group, run the example below for each group.

var samlConfig = SamlIdpConfig.forId("<appUrl>");
var idpGroup = "<idp group name>";
UserGroup.forId("<C3UserGroupId>").addIdpGroupForIdp(samlConfig, idpGroup);

Copy link to this section

Identity Provider Specific Configuration

If you are configuring Microsoft Entra ID consider the additional properties spPostBinding, forcePostBinding, and compressRequest. Accompanying JavaScript code snippets illustrate the application of these settings in the platform's SAML configuration.

Copy link to this section

Microsoft Entra ID

For Microsoft Entra ID, configure the additional settings below.

// Obtain a reference to the SAML configuration
var config = SamlIdpConfig.forId("<AppUrl>");

// update the SAML settings with the parameters specified above.
var settings = config.settings;
settings = settings.withField("spPostBinding", true);
settings = settings.withField("forcePostBinding", true);
settings = settings.withField("compressRequest", false);
settings = settings.withField("compressLogoutRequest", true);

// Update the SAML configuration
config.setConfigValue("settings", settings)

Copy link to this section

See also

• Map Identity Provider Groups

Copy link to this section

Related Types

• Saml
• SamlSettings
• SamlIdpConfig