Guides
Start typing to search…

Agents Integration

Agents Integration

For use cases where Champion would need to call the Client APIs as the user, it is required for the Champion AI Platform to retrieve access tokens for your Client Application users.

Table of Contents

Authentication

Steps

To do this, Champion relies on OAuth2 Authorization Code Flow. This flow, allows Champion (using a client id and secret) to call your application's APIs to exchange an authorization code for an access, refresh and id_token for the user.

  1. Create Authorization Consent Page

    1. Provide a Champion Client Id and Secret to Champion
    2. Allows user to login and consent to Champion acting on their behalf
    3. Redirects user back to Champion w/ Authorization Code

  2. Agent Credentials Token Exchange (OAuth2) with Champion

    1. Create a Champion Consent Form

      • Require user to login and consent to Champion Acting on your behalf
      • Generate Authorization Code and Redirect User to Champion Web Redirect

    2. Provide Following Endpoints for Champion to Exchange Code for Refresh Token

      • Token Endpoint (/token) - Exchanges the authorization code for an access token and refresh token
      • Token Refresh Endpoint (/token) - Obtains a new access token using a refresh token, without requiring user login
      • User Id Endpoint (/userinfo) - Retrieves user profile information for OpenID Connect (OIDC)

Sequence Diagram

Frontend initiated flow

Interaction with Client API

Once the client has granted access to Champion, he can interact with the application by submitting prompts. This diagram illustrates the subsequent flow: how the prompt is processed by the Champion Backend, which then leverages an AWS Bedrock Agent. This agent, in turn, may invoke an AWS Lambda function multiple times. Each Lambda invocation can make one or more calls to the client's external API to gather information or perform actions, ultimately providing a consolidated response back to the user.

Sequence Diagram

Creating a Consent Page

This guide outlines the essential steps to configure a new client within your Identity and Access Management (IAM) platform to enable a frontend-initiated OAuth 2.0 authorization flow. A "client" is often referred to as an "Application" in many IAM systems.

1. Create the Client

First, create a new client registration. You will need to define a Client ID, which is a public, unique identifier for your application.

  • Client ID: A unique string identifying your application (e.g., my-champion-app)
  • Client Secret: A confidential key used to authenticate your application's backend (e.g., s3cr3t_valu3...)

2. Specify Allowed Redirect URIs

You must explicitly tell the IAM platform where it is allowed to send users after they attempt to log in. The platform needs a valid, registered URL to redirect to, whether the authentication succeeds or fails. This is a critical security measure that prevents attackers from redirecting users to malicious sites.

For a given environment, you might need to register several URLs:

  • A specific callback URL: This is where the IAM platform will send the authorization code. Your application's backend will listen on this endpoint to complete the flow.

    • Example: https://api-lab.champion.ai/champion/api/oauth/callback

  • Application URLs: You might also need to add application-level URLs, often using a wildcard, to which users can be redirected after the flow is complete.

    • Example: https://app-lab.champion.ai/champion/app/*

Be mindful of the environment you are configuring. The subdomain should be changed accordingly:

  • Development:

    • api-lab.champion.ai
    • app-lab.champion.ai

  • Pre-production:

    • api-prep.champion.ai
    • app-prep.champion.ai

  • Production:

    • api.champion.ai
    • app.champion.ai

3. Configure OAuth and OpenID Connect Settings

To control the authorization flow and the information your application receives, you will need to configure the following:

  • Scopes: Define the permissions your application can request.

    • openid: A standard scope required for OpenID Connect authentication flows
    • profile: Grants access to the user's default profile claims (name, nickname, picture, etc.)
    • email: Grants access to the user's email address
    • offline_access: Enables your application to request a refresh token, allowing it to obtain new access tokens without requiring the user to log in again

  • Audience: The unique identifier of the API or resource server that the requested token is intended for. In many simple setups, this is often the same as the issuer URL.

    • Audience URL: e.g., https://your-auth-server.com/auth/realms/your-realm

4. Locate Key Endpoints and Issuer Information

Your IAM platform will provide several critical URLs. These are usually found in the general settings for your tenant/realm or within the specific client's configuration details. Champion will use these URLs to orchestrate the authentication flow.

  • Issuer URL: The root URL of the token issuer. This is a primary identifier for the authorization server.

    • e.g., https://your-auth-server.com/auth/realms/your-realm

  • Authorization Endpoint: The URL where your application redirects the user to start the login and consent process.

    • e.g., https://your-auth-server.com/auth/protocol/openid-connect/auth

  • Token Endpoint: The URL your application calls (typically from its backend) to exchange an authorization code for an access token and refresh token.

    • e.g., https://your-auth-server.com/auth/protocol/openid-connect/token

  • Userinfo Endpoint: The URL your application can use to fetch user information, given an access token.

    • e.g., https://your-auth-server.com/auth/protocol/openid-connect/userinfo

  • Introspection Endpoint: A URL for a backend service to check if an access token is active and valid.

    • e.g., https://your-auth-server.com/auth/protocol/openid-connect/token/introspect

5. Finalize Configuration

Save your client configuration. Depending on your security needs, you may need to adjust other settings, such as token expiration times or whether token introspection is enabled.

Once completed, you will have all the necessary values to assemble the JSON configuration object your frontend application needs to initiate the OAuth 2.0 flow.

Example Configuration JSON

Below is an example of the final JSON object that you should provide to the Champion team containing all the necessary configuration parameters.

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret-if-applicable",
  "authorization_endpoint": "https://your-iam-provider.com/auth/realms/your-realm/protocol/openid-connect/auth",
  "token_endpoint": "https://your-iam-provider.com/auth/realms/your-realm/protocol/openid-connect/token",
  "scopes": "openid profile email offline_access",
  "audience": "https://your-iam-provider.com/auth/realms/your-realm",
  "issuer_url": "https://your-iam-provider.com/auth/realms/your-realm",
  "userinfo_endpoint": "https://your-iam-provider.com/auth/realms/your-realm/protocol/openid-connect/userinfo",
  "introspection_endpoint": "https://your-iam-provider.com/auth/realms/your-realm/protocol/openid-connect/token/introspect",
  "success_redirect_url": "https://app-lab.champion.ai/champion/app/oauth/callback/success",
  "error_redirect_url": "https://app-lab.champion.ai/champion/app/oauth/callback/error",
  "allow_access_token_introspection": false
}

Updated 12 days ago