AI Security Gateway

Appearance

XAA (Cross App Access) Configuration Guide ​

🧪 Experimental Feature: XAA is currently an experimental feature supporting Okta's proprietary ID-JAG token format. The feature may change significantly in future releases as cross-app access standards evolve.

XAA Overview ​

Cross App Access (XAA) enables secure cross-application authorization using Okta Identity-JAG tokens. This feature allows applications to access resources on behalf of users across different OAuth clients and identity providers.

What is XAA? ​

XAA provides:

  • ID-JAG Token Exchange: Validate and exchange Okta Identity-JAG tokens for authorized access
  • Client ID Mapping: Map identity provider client IDs to resource authorization server client IDs
  • Token Revocation: Revoke tokens individually or in bulk for security incidents
  • JWKS Caching: Automatic caching of public keys for efficient token validation
  • Audit Logging: Complete tracking of all XAA operations for compliance

XAA Use Cases ​

  • Multi-tenant Applications: Allow users to access resources across different tenant applications
  • Service-to-Service Authorization: Enable backend services to act on behalf of users
  • Cross-domain Access: Authorize access to resources in different security domains
  • Zero-trust Architecture: Validate every request with cryptographically signed tokens

XAA Prerequisites ​

Before configuring XAA, ensure you have:

  1. OAuth Provider Configured: At least one Okta OAuth provider configured in Settings → OAuth Access
  2. Proxy Instance Created: An MCP or LLM proxy instance where XAA will be enabled
  3. Okta Identity-JAG Support: Your Okta organization must support Identity-JAG tokens
  4. Client IDs: Know the client IDs at both the IdP and resource authorization server

XAA Required Information ​

For each client ID mapping, you'll need:

  • IdP Provider ID: The OAuth provider ID from your Gateway settings
  • Client ID at IdP: The OAuth client ID registered with the identity provider (e.g., Okta)
  • Client ID at Resource AS: The OAuth client ID registered with the resource authorization server
  • Allowed Scopes: Space-separated list of OAuth scopes (e.g., openid profile email)

Enabling XAA for a Proxy ​

XAA is enabled on a per-proxy basis by creating client ID mappings. Follow these steps:

Step 1: Access XAA Configuration ​

  1. Navigate to Proxy Management page
  2. Locate the proxy where you want to enable XAA
  3. Click the XAA button on the proxy card

Step 2: Open Client ID Mappings ​

The XAA Configuration modal will open with three sections:

  • Statistics Dashboard: Real-time XAA metrics
  • Client ID Mappings: Configure client mappings (this is where you enable XAA)
  • Token Revocation: Revoke ID-JAG tokens

Navigate to the Client ID Mappings section.

Step 3: Add a Client ID Mapping ​

  1. Click the Add Mapping button

  2. The "Add XAA Client Mapping" dialog will appear

  3. Fill in the required fields:

    FieldDescriptionExample
    IdP ProviderSelect the OAuth provider from the dropdownOkta Production (okta)
    Client ID at IdPEnter the client ID registered with the identity provider0oa5x7y8z9abc123def
    Client ID at Resource ASEnter the client ID for the resource authorization servergateway-mcp-proxy-001
    Allowed ScopesSpace-separated OAuth scopesopenid profile email mcp:tools

  4. Click Create Mapping

Step 4: Verify the Mapping ​

After creation, you should see:

  • The new mapping appears in the Client ID Mappings table
  • The table shows: IdP Provider name, Client ID at IdP, Client ID at Resource AS, Allowed Scopes, and creation date
  • A success message confirms the mapping was created

✅ XAA is now enabled for this proxy!

Managing Client ID Mappings ​

Viewing Existing Mappings ​

The Client ID Mappings table displays all configured mappings for the proxy:

  • IdP Provider: Name of the OAuth provider (e.g., "Okta Production")
  • Client ID at IdP: The client ID registered with the identity provider
  • Client ID at Resource AS: The client ID for the resource server
  • Allowed Scopes: Comma-separated list of authorized scopes
  • Created At: Timestamp when the mapping was created

Editing a Mapping ​

Currently, mappings cannot be edited directly. To modify a mapping:

  1. Delete the existing mapping
  2. Create a new mapping with the updated values

Deleting a Mapping ​

To remove a client ID mapping:

  1. Locate the mapping in the table
  2. Click the Delete button (trash icon) in the Actions column
  3. Confirm the deletion in the dialog
  4. The mapping will be removed immediately

⚠️ Warning: Deleting a mapping will cause ID-JAG token exchange requests for that client ID to fail.

Disabling XAA for a Proxy ​

To completely disable XAA on a proxy:

  1. Open the XAA Configuration modal for the proxy
  2. Navigate to Client ID Mappings
  3. Delete all client ID mappings by clicking the Delete button for each mapping
  4. Close the modal

Result: Without any client ID mappings, the proxy will reject all ID-JAG token exchange requests.

Monitoring XAA Activity ​

Statistics Dashboard ​

The Statistics Dashboard provides real-time metrics:

ID-JAG Tokens ​

  • Total Tokens: Count of all ID-JAG tokens in the system
  • Active Tokens: Non-revoked, non-expired tokens
  • Revoked Tokens: Tokens that have been manually revoked
  • Last Token: Timestamp of the most recent token exchange

JWKS Cache ​

  • Total Providers: Number of identity providers with cached JWKS
  • Total Keys: Total public keys cached for token validation
  • Last Updated: Timestamp of the most recent JWKS refresh

Client Mappings ​

  • Total Mappings: Count of all configured client ID mappings
  • Providers: Number of unique OAuth providers in use
  • Last Updated: Timestamp of the most recent mapping change

The dashboard auto-refreshes every 30 seconds to provide up-to-date information.

Manual Refresh ​

To manually refresh the statistics:

  • Click the Refresh button in the Statistics Dashboard section

Revoking Tokens ​

XAA provides two methods for token revocation:

Revoke Single Token by JTI ​

Use this method to revoke a specific ID-JAG token when you know its unique identifier (JTI):

  1. Navigate to the Token Revocation section
  2. In the "Revoke Single Token" card:
    • Enter the JTI (JWT Token ID) of the token to revoke
    • Optionally, enter a Reason (e.g., "Security incident #12345")
    • Optionally, enter Revoked By (your username or identifier)
  3. Click Revoke Token
  4. A confirmation dialog will appear showing the revocation was successful

When to use: Security incidents, compromised tokens, or user-initiated revocation.

Revoke All Tokens by Subject ​

Use this method to revoke all ID-JAG tokens for a specific user across an identity provider:

  1. Navigate to the Token Revocation section
  2. In the "Revoke by Subject" card:
    • Select the IdP Provider from the dropdown
    • Enter the Subject (user ID or email from the identity provider)
    • Optionally, enter a Reason
    • Optionally, enter Revoked By
  3. Click Revoke Tokens
  4. A success dialog will show how many tokens were revoked

When to use: User account compromise, employee offboarding, or security policy enforcement.

⚠️ Important: Revoked tokens cannot be un-revoked. Users will need to obtain new tokens through the OAuth flow.

XAA Security Best Practices ​

1. Principle of Least Privilege ​

  • Only grant the minimum scopes required for each client mapping
  • Regularly review and remove unused mappings
  • Use specific scopes (e.g., mcp:read_tools) instead of wildcard scopes

2. Regular Audits ​

  • Review XAA statistics weekly to identify unusual patterns
  • Monitor revoked token counts for potential security issues
  • Check audit logs for unauthorized token exchange attempts

3. Token Lifecycle Management ​

  • Set appropriate token expiration times in Okta
  • Revoke tokens immediately upon user offboarding
  • Monitor "Last Token" timestamp for dormant configurations

4. Client ID Protection ​

  • Keep client IDs confidential (treat as sensitive data)
  • Use different client IDs for development, staging, and production
  • Rotate client secrets regularly in Okta

5. Scope Management ​

  • Document why each scope is needed for each mapping
  • Remove scopes that are no longer required
  • Use Okta's scope policies to enforce additional restrictions

XAA Troubleshooting ​

Issue: "Failed to create client mapping" ​

Causes:

  • Database connection error
  • Invalid IdP Provider ID
  • Duplicate client ID mapping

Solutions:

  1. Verify the OAuth provider exists in Settings → OAuth Access
  2. Check that the OAuth provider is enabled
  3. Ensure you're not creating a duplicate mapping (same IdP + Client ID at IdP)
  4. Check server logs for detailed error messages

Issue: Token exchange requests return 401 Unauthorized ​

Causes:

  • No client ID mapping exists for the incoming client ID
  • The ID-JAG token is invalid or expired
  • JWKS public key is not cached or is outdated

Solutions:

  1. Verify a client ID mapping exists for the client ID in the token
  2. Check that the token is valid and not expired
  3. Verify the IdP Provider ID in the mapping matches the token issuer
  4. Check JWKS cache statistics to ensure public keys are available

Issue: Token revocation doesn't work ​

Causes:

  • Incorrect JTI format
  • Subject doesn't match any tokens
  • Database write error

Solutions:

  1. Verify the JTI is the correct format (UUID or base64)
  2. Ensure the subject exactly matches the sub claim in the token
  3. Check that the IdP Provider ID is correct
  4. Review server logs for database errors

Issue: Statistics don't update ​

Causes:

  • Auto-refresh is not working
  • Database query timeout
  • Backend service not running

Solutions:

  1. Click the Refresh button manually
  2. Close and reopen the XAA Configuration modal
  3. Check that the backend API server is running
  4. Verify database connectivity

API Integration ​

For programmatic access to XAA functionality, use the REST API:

Get Client Mappings ​

bash
GET /api/v1/proxies/{proxyId}/xaa/client-mappings

Create Client Mapping ​

bash
POST /api/v1/proxies/{proxyId}/xaa/client-mappings
Content-Type: application/json

{
  "idp_provider_id": 7,
  "client_id_at_idp": "0oa5x7y8z9abc123def",
  "client_id_at_resource_as": "gateway-mcp-proxy-001",
  "allowed_scopes": ["openid", "profile", "email"]
}

Delete Client Mapping ​

bash
DELETE /api/v1/proxies/{proxyId}/xaa/client-mappings/{mappingId}

Get XAA Statistics ​

bash
GET /api/v1/xaa/stats

Revoke Token by JTI ​

bash
POST /api/v1/xaa/revoke-token
Content-Type: application/json

{
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "Security incident",
  "revoked_by": "admin@example.com"
}

Revoke Tokens by Subject ​

bash
POST /api/v1/xaa/revoke-tokens-by-subject
Content-Type: application/json

{
  "idp_provider_id": 7,
  "subject": "user@example.com",
  "reason": "User offboarding",
  "revoked_by": "admin@example.com"
}

For complete API documentation, see API Reference.

XAA Audit Logging ​

All XAA operations are logged for compliance and security monitoring:

Logged Events ​

Event TypeDescriptionLog Fields
xaa_client_mapping_createdClient ID mapping createdproxy_id, idp_provider_id, client_id_at_idp, allowed_scopes
xaa_client_mapping_deletedClient ID mapping deletedproxy_id, mapping_id
xaa_token_exchangeID-JAG token exchangedjti, subject, client_id, scopes
xaa_token_validation_successToken validated successfullyjti, subject, client_id
xaa_token_validation_failedToken validation failedreason, client_id
xaa_token_revokedSingle token revokedjti, reason, revoked_by
xaa_tokens_revoked_by_subjectBulk revocation by subjectsubject, count, idp_provider_id, revoked_by
xaa_jwks_cache_updatedJWKS cache refreshedidp_provider_id, key_count

Viewing Audit Logs ​

Audit logs can be accessed through:

  1. Web Interface: Navigate to System → Audit Logs
  2. Database: Query the audit_logs table
  3. Log Files: Check application logs in logs/ directory
  4. SIEM Integration: Forward to your SIEM system via configured endpoints

Frequently Asked Questions ​

Q: Can I use XAA with non-Okta identity providers? ​

A: Currently, XAA only supports Okta's proprietary ID-JAG token format. Support for other providers may be added in future releases as standards evolve.

Q: How many client ID mappings can I create per proxy? ​

A: There is no hard limit, but for performance reasons, it's recommended to keep mappings under 100 per proxy. Each mapping requires a database query during token exchange.

Q: Are ID-JAG tokens cached? ​

A: Yes, validated ID-JAG tokens are stored in the database with their metadata. The JWKS public keys used for validation are also cached to improve performance.

Q: What happens if I delete a mapping while tokens are active? ​

A: Existing tokens remain valid until they expire or are revoked. However, new token exchange requests for that client ID will be rejected.

Q: Can I use XAA with OAuth Proxy? ​

A: Yes, XAA and OAuth Proxy can be used simultaneously on the same proxy. They serve different purposes: OAuth Proxy handles user authentication, while XAA handles cross-app authorization.

Q: How do I get the JTI of a token? ​

A: The JTI (JWT Token ID) is a claim in the ID-JAG token payload. You can decode the JWT (it's base64-encoded) and extract the jti claim. Note: Do not share JTIs publicly as they can be used to revoke tokens.

Q: Is XAA production-ready? ​

A: XAA is currently marked as experimental. While it's functional and tested, the feature may change significantly in future releases. Use with caution in production and have a rollback plan.

XAA Next Steps ​

Support and Feedback ​

Since XAA is an experimental feature, your feedback is valuable: