AI Agent Protocol Playbooks

# SSO.ID v2 — Identity & Access Management Architecture Spec for AI Agents

## 1. Core Service Endpoints
- **Authorization & Protocol Server (`Auth.SSO.Id`)**: `https://{your-tenant}.sso.id/auth` (or Custom Domain e.g. `https://login.yourdomain.com`)
  - Handles browser redirects, OIDC Discovery (`/auth/.well-known/openid-configuration`), OAuth2 `/auth/oauth/authorize` & `/auth/oauth/token`, SAML 2.0 `/auth/Saml/Login` & `/auth/saml/acs`, and FIDO2 Passkeys `/auth/oauth/passkey/*`.
- **Core Management & Resource API (`Core.SSO.Id`)**: `https://{your-tenant}.sso.id/api`
  - Handles Management REST APIs (`/api/applications`, `/api/users`, `/api/roles`, `/api/organizations`, `/api/connections`, `/api/settings/tenant`, `/api/audit-logs`), SCIM 2.0 (`/api/scim/v2`), and Direct OAuth2 Token Issuance (`/api/oauth2/token`).
- **Admin Console & App Launcher (`angular.sso.id`)**: `https://{your-tenant}.sso.id`

## 2. Multi-Tenant & Regional Headers (For Core Management API Calls)
When calling `https://{your-tenant}.sso.id/api/*` endpoints:
- `Authorization: Bearer ` (Required for authenticated API calls)
- `X-Tenant-Id: ` (Scopes requests to a specific tenant workspace when the user belongs to multiple tenants)
- `X-Region: US | EU` (Optional data residency routing header; defaults to tenant region)

## 3. 4-Tier Policy Inheritance Cascade
SSO.ID v2 evaluates authentication, branding, token lifetimes, and MFA policies across 4 hierarchical tiers:
`Tenant (/settings)` -> `Application (/applications)` -> `Organization (/organizations)` -> `Organization Unit (/organization-units)`
Each lower tier has explicit override flags (`overrideGeneral`, `overrideBranding`, `overrideSecurity`, `overrideTokens`, `overrideMfa`). When an override flag is `true` on an Organization or Organization Unit, passing `organizationId` or `organizationUnitId` to `/auth/oauth/authorize` dynamically enforces that tier's branding, IdP connections, token lifetimes, and MFA rules.

## 4. Discovery & Cryptographic Verification
- **OIDC Discovery Document**: `GET https://{your-tenant}.sso.id/auth/.well-known/openid-configuration?appId=`
- **JWKS Public Keys**: `GET https://{your-tenant}.sso.id/auth/.well-known/jwks.json?appId=`
- **Supported Signing Algorithms**: `RS256` (default asymmetric), `RS384`, `RS512`, `ES256`, `HS256`.

You are an expert identity engineer. Implement OpenID Connect (OIDC) Authentication with PKCE (`S256`) using **SSO.ID v2** in my application.

### 1. SSO.ID v2 Configuration Constants
- `SSO_AUTH_BASE_URL`: `https://{your-tenant}.sso.id/auth` (or custom tenant domain)
- `SSO_API_BASE_URL`: `https://{your-tenant}.sso.id/api`
- `SSO_APP_ID`: ``
- `SSO_CLIENT_ID`: ``
- `SSO_CLIENT_SECRET`: `` (Omit in public SPA/Mobile clients)
- `SSO_REDIRECT_URI`: ``
- `SSO_POST_LOGOUT_REDIRECT_URI`: ``

### 2. Discovery & JWKS Endpoints
- OpenID Configuration: `GET https://{your-tenant}.sso.id/auth/.well-known/openid-configuration?appId=${SSO_APP_ID}`
- JWKS Endpoint: `GET https://{your-tenant}.sso.id/auth/.well-known/jwks.json?appId=${SSO_APP_ID}`

### 3. Step-by-Step OIDC + PKCE Flow to Implement
1. **Generate PKCE & State**:
   - Generate a cryptographically random `code_verifier` (43-128 chars, URL-safe).
   - Compute `code_challenge = BASE64URL(SHA256(ASCII(code_verifier)))`.
   - Generate random `state` and `nonce` strings and store `{ code_verifier, state, nonce }` in `sessionStorage` or an `HttpOnly` cookie.

2. **Redirect to Authorization Endpoint (`GET https://{your-tenant}.sso.id/auth/oauth/authorize`)**:
   Query Parameters:
   - `client_id`: `${SSO_CLIENT_ID}`
   - `response_type`: `code`
   - `redirect_uri`: `${SSO_REDIRECT_URI}`
   - `scope`: `openid profile email roles offline_access`
   - `state`: `${state}`
   - `code_challenge`: `${code_challenge}`
   - `code_challenge_method`: `S256`
   - Optional B2B / Enterprise routing params (if applicable):
     - `organizationId`: `` (Routes login to a specific B2B customer organization's branding/MFA)
     - `organizationUnitId`: `` (Routes login to a specific sub-department)
     - `connectionId`: `` (Bypasses login chooser and jumps straight to an external OIDC/SAML/OAuth2 IdP)
     - `login_hint`: ``

3. **Handle Callback & Exchange Code for Tokens (`POST https://{your-tenant}.sso.id/auth/oauth/token`)**:
   - Verify `state` matches stored state.
   - Send `POST https://{your-tenant}.sso.id/auth/oauth/token` with `Content-Type: application/x-www-form-urlencoded`:
     - `grant_type=authorization_code`
     - `client_id=${SSO_CLIENT_ID}`
     - `client_secret=${SSO_CLIENT_SECRET}` (if confidential backend)
     - `code=${authorization_code}`
     - `redirect_uri=${SSO_REDIRECT_URI}`
     - `code_verifier=${code_verifier}`
   - Expected JSON Response:
     ```json
     {
       "access_token": "eyJhbGciOiJSUzI1NiIs...",
       "id_token": "eyJhbGciOiJSUzI1NiIs...",
       "refresh_token": "def50200...",
       "token_type": "Bearer",
       "expires_in": 3600,
       "scope": "openid profile email roles offline_access"
     }
     ```

4. **Fetch User Profile (`GET https://{your-tenant}.sso.id/auth/oauth/userinfo`)**:
   - Pass header `Authorization: Bearer ${access_token}`.
   - Returns standard OIDC claims (`sub`, `name`, `given_name`, `family_name`, `email`, `email_verified`, `picture`, `roles`, `tenant_id`, `org_id`).

5. **Token Refresh (`POST https://{your-tenant}.sso.id/auth/oauth/token`)**:
   - Send `grant_type=refresh_token&client_id=${SSO_CLIENT_ID}&refresh_token=${refresh_token}`.

6. **RP-Initiated Logout (`GET https://{your-tenant}.sso.id/auth/oauth/logout`)**:
   - Redirect to `https://{your-tenant}.sso.id/auth/oauth/logout?id_token_hint=${id_token}&post_logout_redirect_uri=${encodeURIComponent(SSO_POST_LOGOUT_REDIRECT_URI)}`.

Please generate clean, modular, production-ready code for my framework with full error handling, automatic silent token refresh, and typed user session state.

You are an expert backend systems engineer. Implement an OAuth 2.0 Client Credentials (`client_credentials`) and Token Management client for **SSO.ID v2** with automatic in-memory caching and proactive token renewal before expiry.

### 1. Endpoints Supported by SSO.ID v2
SSO.ID v2 supports token issuance on both the Protocol Server and the Core API:
- Primary Protocol Token Endpoint: `POST https://{your-tenant}.sso.id/auth/oauth/token`
- Direct Core API Token Endpoint: `POST https://{your-tenant}.sso.id/api/oauth2/token`

### 2. Authentication Methods Supported
You may authenticate the confidential client using either:
- **Method A (HTTP Basic Header)**: `Authorization: Basic BASE64(:)`
- **Method B (Form / JSON Body)**: Include `client_id` and `client_secret` in the request body (`application/x-www-form-urlencoded` or `application/json`).

### 3. Machine-to-Machine (`client_credentials`) Request
```http
POST https://{your-tenant}.sso.id/auth/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=&client_secret=&scope=api:read api:write
```

### 4. Token Response Payload
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api:read api:write"
}
```

### 5. Implementation Requirements
1. Create a singleton `SsoIdTokenClient` service that requests an `access_token` using `grant_type=client_credentials`.
2. Cache the token in memory and automatically refresh it 60 seconds before `expires_in` elapses (with concurrency locking so parallel requests do not trigger duplicate token calls).
3. Provide an HTTP client interceptor/middleware that attaches `Authorization: Bearer ` and `X-Tenant-Id: ` to outbound requests to `https://{your-tenant}.sso.id/api` or downstream microservices.
4. Retry once on `401 Unauthorized` by evicting the cached token and fetching a fresh token.

You are an enterprise security engineer. Implement **SAML 2.0 Single Sign-On (SSO) and Single Logout (SLO)** integrating with **SSO.ID v2**.

### Scenario A: SSO.ID v2 as the SAML 2.0 Identity Provider (Your App is the SAML SP)
Use these endpoints on `https://{your-tenant}.sso.id/auth` to configure your application's SAML SP library (e.g., `passport-saml`, `@node-saml/node-saml`, `Sustainsys.Saml2`, `ITfoxtec.Identity.Saml2`, `python3-saml`, or Spring Security SAML):

1. **IdP Metadata XML Endpoint (Auto-Configuration)**:
   - `GET https://{your-tenant}.sso.id/auth/saml/metadata?appId=`
   - Base64-encoded IdP Metadata alternative: `GET https://{your-tenant}.sso.id/auth/saml/GetIDPMetadataBase64?appId=`
   - Core API Application Metadata Lookup: `GET https://{your-tenant}.sso.id/api/applications/metadata?id=`
   - Core API Signing Certificate Download: `GET https://{your-tenant}.sso.id/api/applications/certificate?id=`

2. **IdP Single Sign-On (SSO) Service URL**:
   - `https://{your-tenant}.sso.id/auth/Saml/Login`
   - Supports both **HTTP-Redirect** (`GET /auth/Saml/Login?SAMLRequest=...&RelayState=...`) and **HTTP-POST** (`POST /auth/Saml/Login` with form field `SAMLRequest` and `RelayState`).

3. **IdP Single Logout (SLO) Service URL**:
   - `GET` or `POST` `https://{your-tenant}.sso.id/auth/saml/logout` (Also aliased at `/auth/saml/slo`).

4. **Expected SAML 2.0 Assertion Details**:
   - `NameIDFormat`: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` or `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
   - Signed XML Assertion (`rsa-sha256` / `sha256` digest).
   - Standard Attribute Statements mapped by SSO.ID:
     - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier` (User ID)
     - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` (Email)
     - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` (First Name)
     - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` (Last Name)
     - `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` (Assigned Application Roles)

### Scenario B: SSO.ID v2 as the SAML 2.0 Service Provider (Federating External Okta / Azure AD IdP into SSO.ID)
When configuring an external enterprise IdP to send SAML assertions *into* SSO.ID v2:
- **Assertion Consumer Service (ACS) URL**: `POST https://{your-tenant}.sso.id/auth/saml/acs` (or `https://{your-tenant}.sso.id/auth/saml/acs`)
- **SP Metadata XML URL**: `GET https://{your-tenant}.sso.id/auth/Saml/SPMetadata` or `GET https://{your-tenant}.sso.id/api/connections/sp-metadata`
- **SP X.509 Certificate Download**: `GET https://{your-tenant}.sso.id/api/connections/sp-certificate`

### Implementation Task
Generate the complete SAML 2.0 SP authentication module for my application, including:
1. Dynamic IdP Metadata loading from `https://{your-tenant}.sso.id/auth/saml/metadata?appId=`.
2. SP Metadata generation endpoint (`/saml/metadata`) so I can upload or paste my SP Entity ID and ACS URL into the SSO.ID Admin Console (`/applications` -> Application Settings -> Protocol: SAML 2.0).
3. Login initiation route (`/login/sso`) generating a signed `AuthnRequest` with `RelayState`.
4. Assertion Consumer Service route (`POST /saml/acs`) validating the XML signature, `AudienceRestriction`, `NotBefore`/`NotOnOrAfter` conditions, and `InResponseTo` replay protection, then establishing a local user session.

You are a senior security developer. Implement Direct Password Grant (`grant_type=password`) authentication against **SSO.ID v2** for our trusted first-party client.

### 1. Prerequisites in SSO.ID v2 Admin Console
- In `/applications` -> Application Settings -> **General / Protocol**, ensure **Password** (or OAuth2/OIDC with Password grant enabled) is selected.
- Copy the `Client ID` and `Client Secret`.

### 2. Token Request (`POST https://{your-tenant}.sso.id/auth/oauth/token` or `POST https://{your-tenant}.sso.id/api/oauth2/token`)
Both `application/x-www-form-urlencoded` and `application/json` payloads are supported:
```http
POST https://{your-tenant}.sso.id/auth/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=&client_secret=&username=&password=&scope=openid profile email roles offline_access
```

### 3. Handling Responses & Error Codes
- **200 OK (Authenticated)**:
  ```json
  {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "def50200...",
    "id_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
  ```
- **400 Bad Request (`invalid_grant`)**: Invalid username or password, or account locked due to brute-force lockout policy (`maxFailedLoginAttempts`).
- **403 Forbidden (`mfa_required`)**: If the user or application enforces mandatory Multi-Factor Authentication, guide the user to interactive OIDC flow (`/auth/oauth/authorize`) or step-up MFA verification.

### 4. Implementation Task
Build a login service and UI form that:
1. Submits credentials over HTTPS to our backend proxy (or directly to `/auth/oauth/token` if a native mobile/CLI app).
2. Stores the `access_token` and `refresh_token` securely (`HttpOnly` cookies for web, Keychain/Keystore for mobile).
3. Fetches the user's assigned application menus and roles via `GET https://{your-tenant}.sso.id/auth/oauth/userinfo` and `GET https://{your-tenant}.sso.id/api/users/self`.

You are a WebAuthn / FIDO2 specialist. Integrate **SSO.ID v2 Passkey Registration and Passwordless Authentication** using the browser's `navigator.credentials` WebAuthn API and `https://{your-tenant}.sso.id/auth/oauth/passkey/*` endpoints.

### 1. Passkey Enrollment (Registration Ceremony for Logged-In Users)
1. **Begin Registration (`POST https://{your-tenant}.sso.id/auth/oauth/passkey/register-begin`)**:
   - Send authenticated request with user identifier / session.
   - Receives `PublicKeyCredentialCreationOptions` (`challenge`, `rp`, `user`, `pubKeyCredParams`, `authenticatorSelection`, `excludeCredentials`).
2. **Browser Biometric Ceremony**:
   - Convert Base64URL `challenge` and `user.id` to `Uint8Array`.
   - Call `const credential = await navigator.credentials.create({ publicKey: options })`.
3. **Complete Registration (`POST https://{your-tenant}.sso.id/auth/oauth/passkey/register-complete`)**:
   - Encode `credential.id`, `credential.rawId`, `response.attestationObject`, and `response.clientDataJSON` as Base64URL and POST to `/auth/oauth/passkey/register-complete`.

### 2. Passwordless Sign-In (Assertion Ceremony)
1. **Begin Authentication (`POST https://{your-tenant}.sso.id/auth/oauth/passkey/auth-begin`)**:
   - Optional payload: `{ "username": "[email protected]", "clientId": "" }` (or empty for discoverable resident passkeys).
   - Receives `PublicKeyCredentialRequestOptions` (`challenge`, `rpId`, `allowCredentials`, `userVerification`).
2. **Browser Assertion Ceremony**:
   - Convert Base64URL `challenge` (and `allowCredentials[].id`) to `Uint8Array`.
   - Call `const assertion = await navigator.credentials.get({ publicKey: options })`.
3. **Complete Authentication (`POST https://{your-tenant}.sso.id/auth/oauth/passkey/auth-complete`)**:
   - Send Base64URL-encoded `id`, `rawId`, `response.authenticatorData`, `response.clientDataJSON`, `response.signature`, and `response.userHandle` to `/auth/oauth/passkey/auth-complete`.
   - Receives authenticated redirect / token grant.

Please generate a TypeScript helper utility (`passkeyAuth.ts`) that handles Base64URL <-> ArrayBuffer conversions and implements both `registerPasskey()` and `authenticateWithPasskey()`.

You are an enterprise identity provisioning engineer. Build a **SCIM 2.0 (RFC 7643 / RFC 7644)** client that synchronizes Users and Groups with **SSO.ID v2**.

### 1. Base URLs & Authentication
- **Tenant-Wide SCIM 2.0 Base URL**: `https://{your-tenant}.sso.id/api/scim/v2`
- **Connection-Scoped SCIM 2.0 Base URL**: `https://{your-tenant}.sso.id/api/scim/v2/connections/{connectionId}`
- **Authentication**: `Authorization: Bearer `
  (Generated in the SSO.ID Admin Console under `/settings` -> **Provisioning (SCIM 2.0)** -> `POST /api/settings/tenant/scim/token`, or under `/connections` -> Connection Settings -> **Provisioning** tab).
- **Content-Type**: `application/scim+json` (or `application/json`)

### 2. Discovery Endpoints
- `GET /ServiceProviderConfig` — Returns supported SCIM operations (`patch`, `bulk`, `filter`, `changePassword`, `sort`, `etag`).
- `GET /Schemas` — Returns `urn:ietf:params:scim:schemas:core:2.0:User` and `urn:ietf:params:scim:schemas:core:2.0:Group`.
- `GET /ResourceTypes` — Returns `/Users` and `/Groups` resource definitions.

### 3. SCIM 2.0 User Lifecycle Endpoints (`/Users`)
- **List / Filter Users**: `GET /Users?filter=userName eq "[email protected]"&startIndex=1&count=50`
- **Get User**: `GET /Users/{id}`
- **Create User (`POST /Users`)**:
  ```json
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "externalId": "emp-90210",
    "userName": "[email protected]",
    "name": {
      "givenName": "Alice",
      "familyName": "Vance",
      "formatted": "Alice Vance"
    },
    "emails": [
      { "value": "[email protected]", "type": "work", "primary": true }
    ],
    "active": true
  }
  ```
- **Replace User (`PUT /Users/{id}`)**: Full replacement of user attributes.
- **Partial Update / Deactivate User (`PATCH /Users/{id}`)**:
  ```json
  {
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      { "op": "replace", "path": "active", "value": false }
    ]
  }
  ```
- **Delete / Deprovision User**: `DELETE /Users/{id}` (Executes configured deprovision action: `suspend`, `revoke` sessions, or permanent `delete`).

### 4. SCIM 2.0 Group Lifecycle Endpoints (`/Groups`)
- `GET /Groups`, `GET /Groups/{id}`, `POST /Groups`, `PUT /Groups/{id}`, `DELETE /Groups/{id}` using schema `urn:ietf:params:scim:schemas:core:2.0:Group` with `displayName` and `members: [{ "value": "", "display": "Alice Vance" }]`.

Please implement a resilient SCIM 2.0 provisioning service with idempotent user lookup (`filter=userName eq ...`), creation, attribute updates, group membership sync, and soft/hard deprovisioning.

You are a principal application security engineer. Implement **JWT Bearer Authentication and Fine-Grained RBAC Authorization Middleware** for my backend API using **SSO.ID v2**.

### 1. JWKS & Token Validation Rules
- **Issuer (`iss`)**: `https://{your-tenant}.sso.id/auth` (or custom domain)
- **JWKS URI**: `https://{your-tenant}.sso.id/auth/.well-known/jwks.json?appId=`
- **Algorithms**: `RS256` (default), `RS384`, `RS512`, `ES256`
- **Validation Requirements**:
  1. Fetch and cache public signing keys by `kid` from the JWKS URI (with automatic rotation support when a new `kid` is encountered via `/api/signing-keys/rotate`).
  2. Validate token signature, `exp` (expiration), `nbf` (not before), `iss` (issuer), and `aud` (audience = `` or ``).

### 2. SSO.ID v2 Dynamic RBAC Model (Menus + APIs)
In SSO.ID v2 (`/role-management` and `/applications`), each Application defines:
1. **Hierarchical App Pages / Menus** (`GET https://{your-tenant}.sso.id/api/applications/{appId}/menus`) with granular CRUD flags per Role (`view`, `add`, `update`, `delete`) configured via `PUT /api/roles/{roleId}/applications/{appId}/menu-access`.
2. **Application API Endpoints** (`GET https://{your-tenant}.sso.id/api/applications/{appId}/apis`) mapped to Roles via `PUT /api/roles/{roleId}/applications/{appId}/api-access`.

### 3. Implementation Task
1. Create an authentication middleware/guard that validates incoming `Authorization: Bearer ` headers against SSO.ID's JWKS endpoint and attaches the decoded claims (`sub`, `email`, `roles`, `tenant_id`, `org_id`) to the request context.
2. Create an authorization decorator/middleware `requireRole(...roles)` and `requireMenuPermission(menuCode, action: 'view' | 'add' | 'update' | 'delete')`.
3. Provide a frontend helper endpoint or hook that fetches the authenticated user's permitted navigation tree and CRUD permissions so the UI dynamically hides unauthorized sidebar items and action buttons.