C3 AI Documentation Home

OAuth 2.0 Authorization in the C3 Agentic AI Platform

Open Authorization (OAuth) defines a delegation protocol to allow secure API authorization in a standardized way. OAuth provides third-party applications scoped access to protected resources on behalf of the resource owner.

OAuth is important because it can provide a secure and efficient method for users to share their data without sharing their credentials, ensuring data privacy and security.

The C3 Agentic AI Platform integrates OAuth to ensure secure data access and interactions. It provides tools and configurations to set up and manage OAuth-based authentication seamlessly.

Key terminology

  • client: The application requesting access to the protected resource on behalf of the resource owner. Do not think of the client as a Web browser, or customer who is paying for services. In terms of OAuth, a client is any software that is consuming the API that makes up a protected resource.

  • protected resource: The protected component that the resource owner has access to. A component can be an API for example. The protected resource is available through an HTTP server, and it requires an OAuth token to be accessed.

  • resource owner: The entity who owns the data/resources, or who has access to an API and can delegate access to that API.

  • authorization server: The authorization server provides mechanisms for allowing resource owners to authorize clients, and issues tokens to the client.

  • access token: An access token is a string representing the delegated right of access, encoded as a JSON Web Token (JWT). It is used by applications to make authenticated requests on behalf of the user. The client is responsible for requesting a token from an authorization server and presenting the token to the protected resource. The authorization server is responsible for issuing the token. The protected resource's responsibility is to validate the token.

  • scope: Represents a set of rights at a protect resource. Scopes are represented by strings, and they can be combined into a set by using a space-separated list.

  • grant type: In the OAuth 2.0 specification, a grant type represents the method by which an application gets an access token. A grant type is a way an application asks for permission to access certain data. There are four grant types and the C3 Agentic AI Platform supports two of them.

    • The Client Credentials grant type is an OAuth 2.0 flow where an application requests an access token using its client identifier and client secret. This type is when apps request access to their own resources, not on behalf of a user.
    • The Authorization Code grant type is an OAuth 2.0 flow that involves redirecting the user to an authorization server, obtaining an authorization code, and then exchanging that code for an access token. It is like when an application asks you to log in, and then you get redirected to another page (like Google) to approve access. Once approved, you're sent back to the original app with a special code that the app then trades for the key (access token).

  • redirect url: In the OAuth 2.0 flow, the redirect URL is the location to which the user is sent after they approve (or deny) the app's access request on the authorization server. It's the webpage you're sent back to after you give an app permission to access your data on another app.

OAuth Endpoints

Understanding OAuth endpoints is important when discussing OAuth because these endpoints form the backbone of the OAuth protocol, facilitating the actual processes and flows for authentication and authorization.

OAuth endpoints are URLs provided by the authorization server where certain actions of the OAuth process take place. They handle various stages of the OAuth workflow.

Note: In all these examples, the paths (such as /oauth/authorize, /oauth/token, and /oauth/revoke) might differ based on the authorization server's implementation. You can always check the OAuth server's specific documentation for the correct paths and requirements.

Authorization endpoint

The first endpoint is the authorization endpoint (/oauth/authorize). This is where the client (application) sends the user (resource owner) to authenticate with the service and authorize the client to access their data. The user interacts with this endpoint directly, through their web browser. The user is asked to authenticate and authorize the client to access their data. The URL includes parameters such as client_id, redirect_uri, response_type, scope, and optionally state.

An example of this endpoint might look like this in an HTTP GET request:

Text
https://<authorization-server>.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE&state=STATE

In the above URL:

  • response_type=code indicates that the client expects an authorization code as the response. It must be set to code.

  • client_id is the client's identifier. It is valid client identifier, generated when an OAuthApplication is registered.

  • redirect_uri is where the server sends the user after they have authorized the client, see OAuthApplication for more information.

  • scope is the permissions that the client is requesting.

  • state is an opaque a value used to maintain state between the request and the callback. It is an opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery.

Once the user authenticates and authorizes the client, the server redirects the user to the redirect_uri specified by the client, including an authorization_code as a query parameter. The response from this request can contain:

Text
HTTP/1.1 302 Found
Location: http://example-app.com/callback?code=AUTHORIZATION_CODE&state=STATE

  • code is the authorization code generated by the authorization server. Expires 10 minutes after it is issued. It can only be used one time to obtain an access token.

  • state is the value received from the client in the /oauth/authorize request. The response contains the Cache-Control: no-store and Pragma: no-cache http headers.

Token endpoint

The second is the token endpoint (/oauth/token). This is where the client exchanges the authorization code for an access token. This exchange happens server-to-server, not directly through the user's browser, and includes parameters such as grant_type, code, redirect_uri, and client authentication.

An example of what this might look like is:

Text
POST /oauth/token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXlDM0FJY2xpZW50Om15QzNBSXNlY3JldA==

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

In this request:

  • grant_type=authorization_code indicates that the client is using an authorization code to request an access token. Currently only authorization_code and client_credentials are supported.

  • code is the authorization code that the client received from the authorization server. This is the code returned by the /authorization call.

  • redirect_uri is the same redirect URI that was included in the initial authorization request. If the value is authorization_code grant, must be set to the OAuthApplication redirection_id.

If the request is valid, the server responds with a JSON object containing the access_token and token_type.

An example response might look like:

Text
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"asdf345SGFt45334",
  "token_type":"bearer",
  "refresh_token":"sfdadfafvi99us89etrVDSfg8d0"
}

  • access_token - The access token string as issued by the authorization server.

  • token_type - Currently only 'bearer' tokens are supported.

Revocation endpoint

This is an optional endpoint (/oauth/revoke), and not all authorization servers support it. If supported, clients can use this endpoint to revoke an access token or refresh token. This means the token is no longer be valid for use. The exact behavior might depend on the implementation, but in general, a successful revocation returns a 200 OK status code with an empty response body.

Here is an example request:

Text
POST /oauth/revoke HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXlDM0FJY2xpZW50Om15QzNBSXNlY3JldA==

token=TOKEN_TO_REVOKE

  • token - Token to revoke.

  • token_type_hint - Only access is supported.

An example response might look like this:

Text
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

Grant types

After discussing how OAuth endpoints work on the C3 Agentic AI Platform, it is important to know how these endpoints come together to ensure secure access. This is where OAuth Grant Types come into play. This sections explores these grant types further and see how they fit within the C3 Agentic AI Platform.

The C3 Agentic AI Platform supports OAuth 2.0 authorization through the Authorization Code grant type or Client Credentials grant types. The authorization code grant and client credentials grant types are two different flows for obtaining an access token using the OAuth 2.0 protocol. These flows are appropriate for different types of applications or use cases.

Authorization code grant type

This authorization code grant is used when an application is requesting access to resources on behalf of a user. It is the flow typically used for web applications where the application needs to access resources stored on another server.

In this flow:

  • The client redirects the user to the authorization server to authenticate and authorize the client to access their data.

  • The server redirects the user back to the client with an authorization code.

  • The client exchanges the authorization code for an access token by sending a request to the token endpoint.

An example of an authorization code grant flow can be a web application that uses Microsoft to allow users to log in. The application could redirect users to Microsoft, where they log in and give the application permission to access certain information, like their email. Microsoft then gives the app an authorization code, which the app can exchange for an access token.

Note: This flow offers an extra layer of security by using an authorization code before obtaining the access token.

Client credentials grant type

The client application uses the client credentials grant when it (the client application) needs access on its own behalf, not on behalf of a user. This flow is used when the client application needs to access a resource that it owns. Here, there is no user involved, just the application authenticating itself.

An example of a client credentials grant flow could be a server-side application accessing a service like the Google Cloud Platform's API to analyze text. The application authenticates itself and gets an access token, which it can use to call the Google Cloud API.

  • The client sends its client ID and client secret to the authorization server's token endpoint.

  • If the credentials are valid, the server returns an access token.

If the access token expires, generate a new one instead of refreshing the old access token. The client has constant access to the authorization server as long as the client ID and client secret are valid.

See Generate an Access Token for an example on how to generate an access token using the client credentials grant type.

Access token request

In the context of OAuth, the client application sends a POST request to the authorization server's token endpoint, /oauth/token (the Uniform Resource Locator where the server accepts token requests).

Assume that you have a client with the following credentials:

  • client_id: myC3AIclient

  • client_secret: myC3AIsecret

  • The token endpoint on the authorization server is https://<app url>.c3.ai/oauth/token/

Here's a basic example of what a POST request for an access token might look like:

Text
POST /token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXlDM0FJY2xpZW50Om15QzNBSXNlY3JldA==

grant_type=client_credentials

The client makes a POST request to the /oauth/token endpoint, passing in the following parameters using the Content-Type : application/x-www-form-urlencoded format, with a character encoding of UTF-8 in the body of the HTTP request. The C3 Agentic AI Platform's authorization server would return an access token that can be used to make authenticated requests to the C3 AI API.

The grant_type is required and must be set to client_credentials. The grant_type is a parameter in the request body that tells the authorization server which OAuth 2.0 grant type the application uses to get the access token.

The client_id and client_secret are required. These are the credentials that the client (application) uses to authenticate with the authorization server. Set the client_id to the ID that was generated during the registration of the application with the C3 Agentic AI Platform.

In a client credentials grant flow, the client_id is often included in the request's Authorization header as a base64 encoded string (in the format client_id:client_secret). Some servers may accept these credentials in the request body.

In the example above, the Authorization header, Basic bXlDM0FJY2xpZW50Om15QzNBSXNlY3JldA==, contains the base64 encoded client credentials.

When the authorization server receives this POST request, it checks the client's credentials and the grant type. If everything checks out, it issues an access token. The client can then use this access token to access the protected resources it needs.

Example curl request:

Text
curl -X POST 'https://<app url>/oauth/token/' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -d 'grant_type=client_credentials' \
  -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>"

In this curl request:

  • -X POST specifies the HTTP method to use.

  • The URL after the POST command is the endpoint where the request is made.

  • -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>" provides the credentials for basic authentication where CLIENT_ID and CLIENT_SECRET are replaced with the actual values of your client ID and client secret.

  • -H is used to set the headers for the request.

  • -d is used to send the POST data, in this case, grant_type=client_credentials.

curl takes this and creates a base64-encoded Authorization header for you.

The next section covers the response.

Access token response

The server responds after the client application makes a request to the authorization server for an access token in the client credentials grant flow. If the client's credentials are valid and the request is correctly formed, the C3 AI Platform responds with an access token.

Here is what a typical access token response looks like:

Text
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"99ashdfASFasdf34ASFgdfgg",
  "token_type":"bearer",
  "scope":"example"
}

Let's dissect the above access token response:

  • HTTP/1.1 200 OK: This is the HTTP status code and message indicating that the request was successful.

  • Content-Type: application/json;charset=UTF-8: This header indicates that the body of the response is JSON formatted.

  • Cache-Control: no-store and Pragma: no-cache: These headers indicate that the response must not be cached.

  • access_token: This is the access token that the client application uses to authorize itself when making requests to the resource server (the server hosting the protected resources the client wants to access). The value here, 99ashdfASFasdf34ASFgdfgg, is an example - the actual token is a long string of characters.

  • token_type: This indicates the type of the token. It is usually bearer, which means that whoever bears the token can use it to access resources (no additional identification required).

  • scope: This indicates the scope of the access request. It defines the permissions that the application has with the provided token. In this case, the scope is example, but in real situations, it might be something like read, write, or user:email.

After the client receives the access token, it can use it to access the protected resources on the resource server. The token is included in the Authorization header in each request made to the resource server, typically like this: Authorization: Bearer <access_token>.

When to Use which grant type

  • Authorization Code: Use this when the client application requires access to the user's resources. For instance, if you're building a third-party application that needs to access a user's C3 AI data, you'd use this grant type.

  • Client Credentials: Use this when the client application needs to access its own resources, not on behalf of a user. For example, if you have a backend service that periodically fetches data from the C3 Agentic AI Platform to sync with another system, and this isn't user-specific, this is the grant type to use.

Configuring OAuth

The C3 Agentic AI Platform provides options to configure access token duration, refresh token duration, and authorization code duration. Default values for each are shown below.

  • access token - 2 hours
  • refresh token - 1 year
  • authorization code - 10 minutes

To modify C3 Agentic AI Platform default values, update the OAuthConfig configuration type. For example, to set the access token duration to 1 day, set the accessTokenDuration to 24h as shown.

JavaScript
var config = OAuthConfig.make().getConfig();
config.setConfigValue("accessTokenDuration", "24h");

This document covers the key concepts of OAuth integration with the C3 Agentic AI Platform: client registration, utility functions, and the implementation of OAuth token generation using the Client Credentials Grant and Authorization Code Grant types.

For hands-on examples and practical code samples demonstrating how to obtain OAuth tokens using different grant types, refer to the companion document Obtaining an Access Token.

Related content

Was this page helpful?