Identity Platform Specification

Auth Service
Integration Guide

This page exposes the public integration surface for the central auth service. It is intended for external applications that want to use the service seamlessly as an OAuth2 / OpenID Connect (OIDC) provider.

What this service exposes

The auth service acts as an OAuth2/OpenID Connect provider for registered client applications.

Public Endpoints

GET {AUTH_BASE_URL}/oidc/.well-known/openid-configuration
GET {AUTH_BASE_URL}/oauth/.well-known/openid-configuration
AUTH {AUTH_BASE_URL}/oidc/authorize
POST {AUTH_BASE_URL}/oidc/token
GET {AUTH_BASE_URL}/oidc/userinfo

Note: Replace {AUTH_BASE_URL} with the deployed auth service production instance URL, for example: https://auth.example.com.

Supported Auth Flow

This service mandates and supports the standard OAuth2 Authorization Code Flow with PKCE (Proof Key for Code Exchange).

Authorization Request

client_id redirect_uri response_type=code scope=openid email profile state code_challenge code_challenge_method=S256

Token Exchange Requirements

grant_type=authorization_code code client_id client_secret code_verifier redirect_uri

Note: The token endpoint also accepts Basic auth credentials via the Authorization header.

Redirect URI Validation rules

  • The absolute payload redirect_uri string must explicitly match a registered callback path for the client app.
  • localhost configurations are natively permitted to accelerate local machine testing workflows.
Integration Guides

Structured Code Showcases

Explore end-to-end integration examples across modern web stacks. Use the toggle buttons below to switch frameworks and inspect each layer.

Implementation 01

Vanilla JavaScript Integration

Trigger safe window routing natively to initialize client hooks, then safely offload downstream validation exchange back onto a trusted server layer.

const authBaseUrl = 'https://auth.example.com';
const clientId = 'YOUR_CLIENT_ID';
const redirectUri = 'https://app.example.com/auth/callback';

const state = crypto.randomUUID();
const codeVerifier = crypto.randomUUID();
window.localStorage.setItem('pkce_code_verifier', codeVerifier);

async function sha256(value) {
  const bytes = new TextEncoder().encode(value);
  const digest = await crypto.subtle.digest('SHA-256', bytes);
  return btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

async function login() {
  const codeChallenge = await sha256(codeVerifier);
  const authUrl = new URL(`${authBaseUrl}/oidc/authorize`);
  authUrl.searchParams.set('response_type', 'code');
  authUrl.searchParams.set('client_id', clientId);
  authUrl.searchParams.set('redirect_uri', redirectUri);
  authUrl.searchParams.set('scope', 'openid email profile');
  authUrl.searchParams.set('state', state);
  authUrl.searchParams.set('code_challenge', codeChallenge);
  authUrl.searchParams.set('code_challenge_method', 'S256');

  window.location.href = authUrl.toString();
}
Security Constraint

Never embed or compromise your production client_secret configuration within public web-browser scripts. Always encapsulate authorization code completions entirely at server-side logic points.

Recommended Integration Steps

STEP 01

Register Application

Obtain secure credentials (client_id and client_secret) from management portal.

STEP 02

Whitelist Callbacks

Configure permitted application destination redirect_uri pathways securely.

STEP 03

Validate Discovery

Verify metadata properties against standard provider discovery paths.

STEP 04

Initialize Redirects

Route workflows directly to /oidc/authorize alongside PKCE and state strings.

STEP 05

Backend Resolution

Capture dynamic parameter callbacks to clear final validation steps server-side.

STEP 06

Secure Token Sessions

Store returned security parameters inside high-security session targets.

Core Security Hardening Rules

  • No Secret Check-ins Never check your secret configuration parameters directly into standard Git source control systems.
  • Isolate Public Client Scripts Prevent secret parameters from emitting into customer-accessible web browser scripts.
  • Enforce Cross-Site Tokens Always require un-guessable state keys to protect application connections against injection or CSRF exploits.
  • Enforce Complete PKCE Proofs Require robust PKCE generation strategies to verify transactions originating from native browser setups.