Skip to main content

OIDC & OAuth Interaction Model

Summary​

Keymate uses OpenID Connect (OIDC) and OAuth 2.0 as the protocol foundation for authentication and token issuance. Applications interact with the platform through standard protocol endpoints — authorization, token, userinfo, and discovery — using grant types appropriate to their client type. The platform issues ID tokens for identity verification and access tokens for resource authorization, both carrying claims derived from the user's identity and organizational context.

Why It Exists​

Interoperability demands standard protocols. Applications written in different languages, running on different platforms, and managed by different teams all need a common way to authenticate users and obtain authorization tokens. OIDC and OAuth 2.0 provide this common language. Keymate implements these standards so that any OIDC-compliant application can integrate without proprietary client libraries or custom authentication logic.

Where It Fits in Keymate​

OIDC and OAuth define the protocol-level interactions that authentication flows execute. When a flow completes successfully, the platform uses these protocols to issue tokens. The resulting access tokens carry identity and organizational claims. Federation uses OIDC for identity brokering with external providers. The gateway enforcement layer validates tokens issued through these protocol interactions.

Boundaries​

This page covers protocol-level interactions between applications and the platform. It does not cover:

How It Works​

Discovery and Client Registration​

The platform publishes an OIDC discovery document at the well-known endpoint for each realm. This document advertises the available endpoints, supported grant types, signing algorithms, and capabilities. Applications use this document to configure themselves automatically.

Clients (applications) register with the platform to receive credentials (client ID and, for confidential clients, a client secret). Each client specifies its allowed grant types, redirect URIs, and token configuration. The platform validates all client interactions against this registration.

Grant Types​

The platform supports multiple OAuth 2.0 grant types, each suited to a different interaction pattern:

  • Authorization Code — the standard flow for web applications. The application redirects the user to the platform's authorization endpoint, the user authenticates, and the platform returns an authorization code. The application exchanges the code for tokens at the token endpoint. PKCE (Proof Key for Code Exchange) strengthens this flow against interception attacks.
  • Client Credentials — for machine-to-machine communication. The client authenticates directly with its credentials and receives an access token without user involvement.
  • Direct Grant (Resource Owner Password) — the client collects credentials and submits them directly to the token endpoint. Used for trusted clients where redirect-based flows are impractical.
  • Refresh Token — the client exchanges a refresh token for a new access token without requiring the user to re-authenticate.

Token Endpoints​

The platform exposes several protocol endpoints:

  • Authorization endpoint — initiates interactive authentication and returns an authorization code
  • Token endpoint — exchanges authorization codes, credentials, or refresh tokens for access tokens and ID tokens
  • Userinfo endpoint — returns claims about the authenticated user, based on the scopes granted
  • Introspection endpoint — validates a token and returns its active state and claims. Keymate's enhanced introspection also checks organizational context validity and session state.
  • Revocation endpoint — invalidates an access token or refresh token

ID Token and Access Token​

The platform issues two distinct token types:

  • ID Token — a signed JWT containing identity claims (subject identifier, authentication time, issuer). Applications use the ID token to verify the user's identity. The ID token is for the client, not for resource servers.
  • Access Token — a signed JWT containing authorization claims (roles, organizational context, custom attributes). Resource servers validate the access token to authorize requests. The access token carries the user's active Tenant and department context.

OAuth scopes control which claims appear in tokens and which resources the client can access. Standard OIDC scopes (openid, profile, email) govern identity claims. Custom scopes can map to additional attribute projections or resource access grants. The platform evaluates scope requests against the client's allowed scopes and the user's consent decisions.

Protocol Mappers​

Protocol mappers transform identity data into token claims during token issuance. The platform applies mappers based on the client configuration — each client can define which identity attributes, roles, and organizational context appear in its tokens. Mappers enable per-client claim customization without modifying the underlying identity data.

Diagram​

Example Scenario​

Scenario​

A web application integrates with Keymate using the Authorization Code flow with PKCE. The user authenticates, selects a department context, and the application receives tokens. The application then calls a backend API, which validates the access token through introspection.

Input​

  • Actor: Web application configured as a confidential OIDC client
  • Resource: Backend API protected by access token validation
  • Action: Authorization Code flow with PKCE, followed by API call
  • Context: User holds assignments in two departments; selects Finance department during authentication

Expected Outcome​

  • Applied — The application receives an ID token confirming the user's identity and an access token carrying Finance department roles and context. The backend API introspects the access token, confirms it is active with valid Finance department access, and authorizes the request.
  • Why: The Authorization Code flow with PKCE establishes authentication. Protocol mappers project the active organizational context into the access token. Enhanced introspection validates both the token and the department context.

Common Misunderstandings​

  • "The ID token is used to authorize API requests" — No. The ID token verifies the user's identity for the client application. Resource servers use the access token for authorization decisions.

  • "All clients use the same grant type" — No. The appropriate grant type depends on the client type. Web applications use Authorization Code, backend services use Client Credentials, and trusted clients may use Direct Grant.

  • "Scopes automatically grant access to resources" — No. Scopes control which claims appear in tokens. Resource access decisions depend on the authorization layer evaluating the token's claims against policies.

warning

Avoid using the Direct Grant flow for public-facing applications. This flow transmits credentials directly, which increases exposure risk. Use Authorization Code with PKCE for browser-based and mobile applications.

Design Notes / Best Practices​

  • Use Authorization Code with PKCE as the default grant type for all interactive applications. PKCE prevents authorization code interception without requiring a client secret.
  • Configure protocol mappers per client to minimize token size. Include only the claims that each application requires for its authorization decisions.
  • Use the introspection endpoint for resource servers that need real-time token validation, especially when organizational context changes may invalidate previously issued tokens.
tip

Register each application as a separate OIDC client with its own redirect URIs and allowed scopes. Sharing client registrations across applications creates security boundaries that are difficult to manage.

  • Integrating a web application using Authorization Code flow with PKCE
  • Configuring machine-to-machine authentication with Client Credentials
  • Customizing token claims per application through protocol mappers
  • Validating tokens with enhanced introspection that checks organizational context

Authentication Flows

How flows execute before protocol interactions

Token Claims & Context

Claim structure produced by protocol interactions

Federation & External IdPs

OIDC-based identity brokering with external providers

Token Exchange Model

Post-authentication context switching via token exchange