OAuth 2.0 & OpenID Connect

Understanding OAuth 2.0 and OpenID Connect is foundational to integrating with Auris correctly. This page explains the protocols, their differences, the grant types supported by Auris, and how Auris implements them internally.

What is OAuth 2.0?

OAuth 2.0 (RFC 6749) is an authorization framework. It provides a standard way for a user to grant a third-party application limited access to their resources on another service, without exposing their credentials to the third-party application.

The key insight is that OAuth 2.0 is about delegating access — not about verifying identity. When you log into a third-party app using “Sign in with Google,” Google is using OAuth 2.0 to grant the app access to your profile data, not to prove that you are who you say you are. That is a separate layer.

Core Roles in OAuth 2.0

In Auris, the Authorization Server and Resource Server are part of the same platform — your Auris deployment. The Client is your application, and the Resource Owner is your user.

What OAuth 2.0 Is Not

OAuth 2.0 does not:

• Define how a user proves their identity (no login protocol)
• Specify what information is in an access token
• Define how tokens are validated by resource servers

These gaps led to the creation of OpenID Connect.

What is OpenID Connect?

OpenID Connect (OIDC) is an authentication layer built on top of OAuth 2.0. It answers the question OAuth 2.0 leaves unanswered: “Who is this user?”

OIDC extends the OAuth 2.0 Authorization Code flow by introducing:

1. The ID Token — a signed JWT containing the user’s identity (user ID, email, name, etc.)
2. The UserInfo Endpoint — where the client can retrieve additional user claims
3. Standardized Claims — a defined set of claim names (sub, email, name, picture, etc.)
4. Discovery Document — a well-known URL that describes the provider’s endpoints

When you use OIDC, you request the openid scope in addition to any other scopes. The presence of openid in the scope tells the authorization server to issue an ID Token alongside the access token.

The Difference in Practice

In Auris, every hosted login flow is OIDC — the openid scope is included by default, and the token response always contains an ID token in addition to access and refresh tokens.

Grant Types Supported by Auris

OAuth 2.0 defines several “grant types” — flows for obtaining tokens depending on the type of client and use case.

1. Authorization Code + PKCE (Recommended)

The standard flow for user-facing applications (web apps, mobile apps, SPAs, CLIs with browser redirect). PKCE (Proof Key for Code Exchange, RFC 7636) is added to protect against code interception attacks.

When to use: Any application where a real user logs in interactively.

Flow summary:

1. App generates a code verifier and code challenge
2. Browser is redirected to the Auris hosted login page with the code challenge
3. User authenticates
4. Auris redirects back to the app with an authorization code
5. App exchanges the code + code verifier for tokens

See the PKCE Flow page for a full step-by-step walkthrough.

2. Client Credentials (M2M)

Used for machine-to-machine communication where no user is involved. A service authenticates using its client_id and client_secret to obtain an access token with server-defined scopes.

When to use: Backend services, scheduled jobs, CI/CD pipelines, internal microservices.

Flow summary:

1. Service sends client_id and client_secret to the token endpoint
2. Auris validates the credentials and issues an access token with the allowed scopes
3. Service uses the token to call protected APIs

curl -X POST https://api.altovar.net/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "m2m-service-id",
    "client_secret": "m2m-service-secret",
    "scope": "read:users manage:roles"
  }'

The resulting access token has "type": "m2m" in its payload and carries only the declared scopes — no user identity.

3. Device Authorization Grant (RFC 8628)

For devices that cannot open a browser directly: smart TVs, CLI tools, IoT devices, game consoles.

When to use: Input-constrained devices or CLI tools that cannot redirect the user’s browser.

Flow summary:

1. Device requests a device code and user code from Auris
2. Auris returns a device_code, user_code, and verification_url
3. Device displays the user_code and asks the user to go to the verification_url on another device
4. User authenticates on their phone or computer and approves the device
5. Device polls the token endpoint until the user approves
6. Token endpoint returns tokens once approved

4. Token Exchange (RFC 8693)

Allows one token to be exchanged for another — used for impersonation and delegation scenarios in complex multi-service architectures.

When to use: Backend services that need to act on behalf of a user, or admin tools that need to impersonate a user for debugging.

Token exchange produces an access token with an act claim identifying the actor (the service performing the exchange) and the sub of the original user. Requires the impersonate:users or delegate:tokens permission.

5. CIBA (Client-Initiated Backchannel Authentication)

An OpenID Connect extension (CIBA, pronounced “see-bah”) that allows a client to initiate authentication for a user without a browser redirect. Instead, the user receives a push notification or out-of-band message and approves or rejects the authentication request.

When to use: Call center authentication, IoT approvals, high-assurance flows where you want to authenticate the user on a separate trusted device.

Auris supports CIBA in poll, ping, and push modes.

OAuth 2.0 Endpoints in Auris

Scopes in Auris

OAuth 2.0 scopes are space-separated strings that define what access a token grants. Auris supports both standard OIDC scopes and custom M2M scopes.

Standard OIDC Scopes

M2M Scopes

M2M tokens use custom scopes defined per application in the Console. Examples:

• read:users — read-only access to user data
• manage:roles — full CRUD on roles
• read:audit-logs — access to the audit log API

Scopes are validated at the token endpoint: if a client requests a scope not listed in its allowed scopes configuration, the request is rejected.

How Auris Implements OAuth 2.0

Auris is built on Keycloak as the underlying identity engine, with Auris extending and wrapping Keycloak’s functionality. The integration works at two levels:

Keycloak as the Base Engine

Keycloak handles:

• User credential storage and verification
• Session management and token issuance
• SAML and OIDC federation
• Social login protocol bridges

Auris Extensions on Top

Auris adds on top of Keycloak:

• Hosted Login Pages: Fully branded, custom-domain login UI (Keycloak’s default UI is replaced)
• Actions Engine: Custom server-side code hooks that run during login, signup, and token issuance
• Custom JWT Claims: Per-application configurable claim injection at token issuance time
• PKCE Enforcement: Enforced at the Auris layer (not optional)
• Adaptive MFA: Risk scoring and step-up authentication based on IP, device, and behavior
• FGA Integration: Fine-grained authorization checks at the resource level, beyond Keycloak’s role-based model

When the Auris SDK calls loginWithRedirect(), it constructs the authorization URL and redirects the browser to the Auris hosted login page, which coordinates with Keycloak for the actual credential verification, then issues tokens through the Auris token endpoint.

Related Concepts

• Tokens Explained — Access tokens, refresh tokens, and ID tokens in detail
• PKCE Flow — Authorization Code flow with Proof Key for Code Exchange
• Hosted Login (Universal Login) — How Auris implements OAuth2 via hosted pages
• Hosted Login Guide — Step-by-step PKCE integration
• M2M Client Credentials — Server-to-server OAuth2 flow
• Authentication API — Token endpoints, login, and OAuth2 grants
• Authentication Settings — Configure allowed grant types and MFA