Authentication

Keycard implements standard OAuth 2.1 authorization flows with PKCE (Proof Key for Code Exchange) to provide secure, delegated authentication for AI agents and applications.

Overview

When a user interacts with a Keycard-protected application:

1. User initiates authentication
2. Application redirects to Keycard
3. Keycard redirects to the zone’s identity provider
4. User authenticates with their identity provider
5. Identity provider returns to Keycard with authorization
6. Keycard issues tokens and creates session
7. User is redirected back to application with active session

All authentication flows follow OAuth 2.1 standards with additional security hardening through PKCE.

---

OAuth 2.1 Authorization Code Flow

Keycard implements the OAuth 2.1 Authorization Code Flow, the most secure OAuth flow for applications that can securely store client secrets.

Flow Diagram

sequenceDiagram
    participant User
    participant App as Application
    participant KC as Keycard
    participant IDP as Identity Provider

    User->>App: Click "Login"
    App->>KC: Redirect to /oauth/authorize
    KC->>IDP: Redirect to IdP login
    IDP->>IDP: User enters credentials
    IDP->>KC: Auth code
    KC->>IDP: Exchange code for tokens
    IDP->>KC: ID token + access token
    KC->>App: Redirect with session
    App->>User: Logged in

Step-by-Step Breakdown

1. Authorization Request

Application redirects user to Keycard:

GET https://z-abc123.keycard.cloud/oauth/authorize?
  response_type=code&
  client_id=<application-client-id>&
  redirect_uri=https://app.example.com/callback&
  scope=openid profile email&
  state=<random-state>&
  code_challenge=<pkce-challenge>&
  code_challenge_method=S256

Parameters:

• response_type=code: Request authorization code
• client_id: Application’s registered client ID
• redirect_uri: Where to send user after authentication
• scope: Requested permissions (OpenID Connect scopes)
• state: Random value to prevent CSRF attacks
• code_challenge: PKCE code challenge (see below)
• code_challenge_method: Hash method for PKCE (S256 = SHA256)

2. Identity Provider Redirect

Keycard redirects to the zone’s configured identity provider:

GET https://idp.example.com/authorize?
  response_type=code&
  client_id=<keycard-client-id>&
  redirect_uri=https://z-abc123.keycard.cloud/oauth/callback&
  scope=openid profile email&
  state=<keycard-state>

3. User Authentication

User authenticates with their identity provider:

• Enters username and password
• Completes MFA if required
• Identity provider validates credentials

4. Authorization Code Grant

Identity provider redirects back to Keycard with authorization code:

GET https://z-abc123.keycard.cloud/oauth/callback?
  code=<authorization-code>&

Token Exchange

Keycard implements RFC 8693 OAuth 2.0 Token Exchange to enable secure, delegated access to protected resources. This allows applications to exchange one type of token for another, enabling AI agents and MCP servers to access resources on behalf of authenticated users.

Read more in Token Exchange.

High-Level Flow

sequenceDiagram
    participant User
    participant Agent as AI Agent/MCP Server
    participant KC as Keycard
    participant Resource as External Resource

    User->>Agent: Make request
    Agent->>KC: Exchange token for GitHub access
    KC->>Resource: Request user's GitHub token
    Resource->>User: Authorize access
    User->>Resource: Grant permission
    Resource->>KC: GitHub access token
    KC->>Agent: Exchanged token
    Agent->>Resource: Access GitHub API
    Resource->>Agent: API response
    Agent->>User: Result