Outseta provides standard .well-known endpoints that enable automated discovery and configuration of OAuth 2.0 and OpenID Connect (OIDC) settings. These endpoints follow industry standards defined in RFC 5785 and the OpenID Connect Discovery specification.

What are .well-known Endpoints?

Well-known URIs are standardized locations where services publish machine-readable metadata about their configuration. These endpoints allow client applications to automatically discover authentication settings without manual configuration, making integrations more robust and easier to maintain.

Available Endpoints

Outseta provides two key well-known endpoints:

1. OpenID Connect Discovery Document

Endpoint: https://<your-subdomain>.outseta.com/.well-known/openid-configuration

This endpoint returns a JSON document containing metadata about Outseta's OAuth 2.0 and OpenID Connect implementation, including:

  • Authorization endpoint URL
  • Token endpoint URL
  • UserInfo endpoint URL
  • JWKS URI (JSON Web Key Set location)
  • End session and revocation endpoints
  • Supported scopes, response types, and grant types
  • Supported signing algorithms
  • Claims and authentication methods supported
  • Other OIDC provider capabilities

Example response structure:

{
  "issuer": "https://<your-subdomain>.outseta.com",
  "jwks_uri": "https://<your-subdomain>.outseta.com/.well-known/jwks",
  "authorization_endpoint": "https://<your-subdomain>.outseta.com/connect/authorize",
  "token_endpoint": "https://<your-subdomain>.outseta.com/connect/token",
  "userinfo_endpoint": "https://<your-subdomain>.outseta.com/connect/userinfo",
  "end_session_endpoint": "https://<your-subdomain>.outseta.com/connect/endsession",
  "revocation_endpoint": "https://<your-subdomain>.outseta.com/connect/revocation",
  "introspection_endpoint": "https://<your-subdomain>.outseta.com/connect/introspect",
  "scopes_supported": ["email", "openid", "profile", "outseta"],
  "response_types_supported": ["code", "token", "id_token", "id_token token", "code id_token", "code token", "code id_token token"],
  "grant_types_supported": ["authorization_code", "client_credentials", "password", "refresh_token", "implicit"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["plain", "S256"],
  "claims_supported": ["email", "email_verified", "sub", "name", "family_name", "given_name", ...]
}

2. JSON Web Key Set (JWKS)

Endpoint: https://<your-subdomain>.outseta.com/.well-known/jwks

This endpoint returns the public keys used by Outseta to sign JWT access tokens. Your application uses these keys to verify that tokens are authentic and haven't been tampered with.

Example response structure:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-here",
      "n": "modulus-value...",
      "e": "AQAB",
      "alg": "RS256"
    }
  ]
}

Common Use Cases

Verifying JWT Tokens Server-Side

When your backend receives an Outseta JWT access token, you should verify it using the public keys from the JWKS endpoint:

// Node.js example using jose library
import * as jose from 'jose';

const JWKS = jose.createRemoteJWKSet(
  new URL('https://your-domain.outseta.com/.well-known/jwks')
);

try {
  const { payload } = await jose.jwtVerify(accessToken, JWKS);
  console.log('Token is valid:', payload);
  // Access user info: payload.sub, payload['outseta:accountUid'], etc.
} catch (error) {
  console.error('Token verification failed:', error);
}

👉 Complete example: Decode and verify Outseta JWT Access Tokens server-side

Integrating with Third-Party OIDC Clients

Many authentication libraries and platforms support automatic configuration via the OpenID Connect discovery endpoint:

// Example configuration for an OIDC client
const config = {
  issuer: 'https://your-domain.outseta.com',
  // The client will automatically fetch from:
  // https://your-domain.outseta.com/.well-known/openid-configuration
  clientId: 'your-oauth-client-id',
  clientSecret: 'your-oauth-client-secret',
  redirectUri: 'https://your-app.com/callback'
};

Token Exchange Pattern (Supabase Integration)

A common pattern is exchanging an Outseta JWT for another service's JWT, using the JWKS endpoint for verification:

// Supabase Edge Function example
import * as jose from 'https://deno.land/x/[email protected]/index.ts';

const JWKS = jose.createRemoteJWKSet(
  new URL(`https://${Deno.env.get('OUTSETA_DOMAIN')}/.well-known/jwks`)
);

// Verify the Outseta JWT
const { payload } = await jose.jwtVerify(outsetaToken, JWKS);

// Create new JWT for Supabase with verified claims
const supabaseJwt = await new jose.SignJWT(payload)
  .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
  .setIssuer('supabase')
  .sign(supabaseSecret);

👉 Complete example: Supabase Integration with Outseta Auth

Key Benefits

Automated Configuration: Client libraries can automatically discover endpoints without hardcoding URLs.

Key Rotation Support: When Outseta rotates signing keys, your application automatically fetches the new keys from the JWKS endpoint.

Standards Compliance: Following OpenID Connect Discovery standards ensures compatibility with a wide range of authentication libraries and platforms.

Security: Verifying tokens with public keys from the JWKS endpoint ensures tokens are authentic and haven't been modified.

Best Practices

  1. Cache the Discovery Document: The OpenID configuration rarely changes, so cache it according to HTTP cache headers to reduce requests.
  2. Refresh JWKS Periodically: Fetch the JWKS on application startup and refresh it periodically (e.g., every 24 hours) to handle key rotation.
  3. Handle Multiple Keys: The JWKS endpoint may return multiple keys during rotation periods. Always match tokens using the kid (key ID) from the JWT header.
  4. Use Libraries: Instead of manually parsing and verifying JWTs, use established libraries like jose, jsonwebtoken, or platform-specific OIDC clients.

Related Resources