OAuth/OIDC Integration Profile

Candidate profile — 2 August 2026 This document describes the target integration contract and the currently intended first-client topology. It is not a public claim that every OIDC discovery endpoint or grant is already available.

Objective

ANUKA needs reusable sign-in without turning identity into blanket authorization, cross-product surveillance, or a global reputation system.

The governing rule is:

Authenticate a person at the right boundary; authorize every product action at the product boundary.

auth.anuka.pro is the user-facing login and consent host. The first relying product is ANUKA Goals at goals.anuka.pro. The authorization service behind the consent host issues and validates the authorization result; the product owns its own session, data, and permissions.

Roles and current first-client topology

Role	Initial value	Responsibility
Authorization/consent host	https://auth.anuka.pro	sign-in, account recovery, consent display, safe handoff
OAuth/OIDC authorization service	configured service behind the consent host	authorization request, authorization code, token issuance and revocation
Relying party / client	https://goals.anuka.pro	user experience, local session, product authorization and data
Registered callback	https://goals.anuka.pro/auth/callback	exact code-and-state return endpoint

The exact issuer, discovery URL, signing key set, token endpoint, and client-registration mechanism must be recorded in ADR-001 through ADR-003 before claiming full OIDC discovery conformance.

Browser authorization-code flow

Interactive authorization flow

One consented handoff, not blanket access

Select a step to see the security boundary that must hold before the flow continues.

1 Start 2 Prepare 3 Request 4 Consent 5 Decision 6 Callback 7 Validate 8 Exchange 9 Claims 10 Local session

User

Start. A person chooses sign-in in ANUKA Goals.

Security boundary Goals must begin a new, product-scoped authorization transaction.

1. 1. Start. A person chooses sign-in in ANUKA Goals.
2. 2. Prepare. Goals creates state, nonce, and a PKCE verifier and challenge.
3. 3. Request. Goals sends an authorization request with its client ID, exact callback, scope, state, and PKCE challenge.
4. 4. Consent. The login and consent surface identifies the client, destination, requested scope, and cancellation route.
5. 5. Decision. The person approves or denies the consent request.
6. 6. Callback. The service returns an authorization code and state, or an error, only to the exact registered callback.
7. 7. Validate. Goals validates state and nonce and binds the code to the originating session.
8. 8. Exchange. Goals exchanges the code with the PKCE verifier; confidential credentials remain server-side.
9. 9. Claims. The service issues tokens or claims for the registered audience.
10. 10. Local session. Goals creates its own product-local session and authorizes only product actions.

Mandatory safeguards

• Use authorization code with PKCE (S256) for browser and native public clients. Do not use the implicit flow.
• Register exact redirect URIs; reject wildcards, fragments, open redirects, and unregistered schemes except separately approved native-app patterns.
• Generate high-entropy state; validate it before accepting a response. Use and validate nonce for OIDC ID tokens.
• Bind the authorization code to the client, redirect URI, PKCE challenge, user session, and short expiry. Never log authorization codes, verifier values, access tokens, refresh tokens, or goal content.
• Treat auth.anuka.pro redirects as security-sensitive allowlists. User-provided redirect_to must never determine an arbitrary destination.
• Keep confidential client secrets server-side. A browser exchanges via a same-origin backend when client authentication is required; it never receives the secret.
• Validate issuer, audience, signature, expiry, authorized party/client, nonce where applicable, and token binding before creating a client session.
• Rotate signing and client credentials; publish a revocation, logout, recovery, and incident path.

Minimal claims and scopes

The first client asks for the smallest account-access information necessary to create a local Goals session.

Item	Initial policy
stable subject	a pairwise or otherwise product-scoped subject is preferred; do not expose a universal public identifier by default
profile fields	no optional profile, organization, reputation, or contribution claims without a documented product need and consent
email	request only if required for account recovery, notification, or another documented purpose
scopes	narrow account/session scope; any product API scope is separately named, limited, and revocable
assurance	Goals begins at A1 account-controlled participation; sensitive actions may add explicit step-up later

Authentication success alone does not prove legal identity, organizational authority, eligibility, reputation, or consent to share data with another product.

Consent, session, logout, and recovery

The consent screen must identify the client, exact redirect destination, requested scope, and cancellation route in understandable language. A previous grant does not override a changed client, redirect URI, scope, purpose, or material policy change.

Goals maintains its own product-local session. Single logout and back-channel logout are deferred until an ADR defines the security and user-experience semantics. A user must be able to sign out of Goals without implying deletion of the shared account; deletion and recovery are purpose- and service-specific.

Client registration and operations

Initial registration is manual and reviewable. Every client record has an owner, product, environment, exact redirect URIs, allowed grants, scopes, token lifetime policy, audience/resource policy, data purpose, support contact, and review date. Register development, preview, and production clients separately. Disable a client immediately when its ownership or redirect safety is uncertain.

The authorization host and the first client must test approval, denial, expired request, expired code, PKCE failure, state/nonce mismatch, redirect mismatch, account recovery, logout, revoked grant, and unavailable-service states. Security events capture minimal metadata necessary to investigate; product content remains outside identity logs.

Interoperability path

The first implementation may operate with a configured authorization endpoint and a consent UI before all OIDC discovery endpoints are published. When discovery is adopted, publish and version the issuer configuration, authorization endpoint, token endpoint, JWKS URI, supported response/grant types, PKCE methods, scopes, claims, authentication methods, and end-session/revocation endpoints only after they are verified in production-like tests.