External authentication providers

Use an external identity provider when users already authenticate through Auth0, Clerk, or Amazon Cognito. The provider issues a JWT, the generated service verifies its signature and claims, and Apso maps the result into a common auth context.

Required inputs

Every generated JWT strategy needs:

• issuer: the trusted token issuer URL
• audience: the API audience or client identifier expected in the token
• algorithms: accepted signature algorithms, usually RS256
• Optional jwksUri: the provider’s public signing-key endpoint
• Claim mappings for user ID, workspace or organization, roles, and email

Provider configuration

{
  "auth": {
    "provider": "auth0",
    "jwt": {
      "issuer": "https://your-tenant.us.auth0.com/",
      "audience": "https://api.example.com",
      "algorithms": ["RS256"]
    },
    "claims": {
      "userId": "sub",
      "email": "email",
      "workspaceId": "https://example.com/workspace_id",
      "roles": "https://example.com/roles"
    }
  }
}

{
  "auth": {
    "provider": "clerk",
    "jwt": {
      "issuer": "https://your-clerk-domain.example.com",
      "audience": "project-api",
      "algorithms": ["RS256"]
    },
    "claims": {
      "userId": "sub",
      "email": "email",
      "workspaceId": "org_id",
      "roles": "roles"
    }
  }
}

{
  "auth": {
    "provider": "cognito",
    "jwt": {
      "issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example",
      "audience": "your-app-client-id",
      "algorithms": ["RS256"]
    },
    "claims": {
      "userId": "sub",
      "email": "email",
      "workspaceId": "custom:workspace_id",
      "roles": "cognito:groups"
    }
  }
}

Replace every example issuer, audience, and claim path with the values from your provider. Do not infer these from a frontend configuration.

Generate and inspect

apso schema validate
apso generate

Inspect the generated auth guard and framework configuration. Confirm the header and claim names before connecting a client.

Send the user token

curl -s https://api.example.com/Projects \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

The token belongs to the signed-in user. Keep a hosted Apso service key in a BFF or another trusted process because it is a separate server credential.

Add an unsupported provider

Firebase Auth, Supabase Auth, and another issuer can be integrated through custom code under extensions/. Implement the provider’s documented verification method, then normalize the result into the same fields used by the generated scoping layer:

export interface AuthContext {
  userId?: string;
  email?: string;
  workspaceId?: string;
  organizationId?: string;
  roles: string[];
}

Register the custom guard through the extension module and suppress or replace the generated HTTP boundary where the framework requires it. Keep provider SDK initialization and secret values outside autogen/.

Test the boundary

1. Reject a request without a token.
2. Reject an expired token.
3. Reject a token with the wrong issuer or audience.
4. Accept a valid token and map the user ID.
5. Verify the workspace claim scopes generated resources.
6. Verify a user cannot supply another workspace ID in a create body.
7. Verify privileged role bypasses are explicit and tested.