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
{AUTH_BASE_URL}/oidc/.well-known/openid-configuration
{AUTH_BASE_URL}/oauth/.well-known/openid-configuration
{AUTH_BASE_URL}/oidc/authorize
{AUTH_BASE_URL}/oidc/token
{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
Token Exchange Requirements
Note: The token endpoint also accepts Basic auth credentials via the Authorization header.
Redirect URI Validation rules
-
The absolute payload
redirect_uristring must explicitly match a registered callback path for the client app. -
localhostconfigurations are natively permitted to accelerate local machine testing workflows.
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.
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
Register Application
Obtain secure credentials (client_id and client_secret) from management portal.
Whitelist Callbacks
Configure permitted application destination redirect_uri pathways securely.
Validate Discovery
Verify metadata properties against standard provider discovery paths.
Initialize Redirects
Route workflows directly to /oidc/authorize alongside PKCE and state strings.
Backend Resolution
Capture dynamic parameter callbacks to clear final validation steps server-side.
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.