OAuth 2.0 & OpenID Connect SSO

The OAuth 2.0 Authorization Code Flow is the recommended and most secure flow for most applications, including web apps and single-page applications (SPAs). It uses PKCE (Proof Key for Code Exchange) for public clients to prevent authorization code interception attacks.

Best for: Web applications, SPAs, mobile apps, third-party integrations

Use refresh tokens to obtain new access tokens without requiring the user to sign in again. Refresh tokens are valid for 14 days and can be rotated to maintain security.

Best for: Long-lived sessions, background services, offline access

The OAuth 2.0 Resource Owner Password Credentials flow is supported for backward compatibility with legacy integrations. New integrations should use the Authorization Code Flow instead.

Best for: Legacy applications, internal tools (not recommended for new development)

GET /connect/authorize

Initiates the OAuth authorization flow. Redirects user to sign in with their identity provider (Microsoft, Google, or email/password).

Query Parameters:

• client_id (required): Your application ID
• redirect_uri (required): URL to redirect after authentication
• response_type (required): Must be 'code'
• scope (required): Space-separated list of scopes (openid, email, profile, offline_access, roles)
• code_challenge (required for SPA): PKCE code challenge
• code_challenge_method (required with code_challenge): 'S256'
• state (recommended): Random string to prevent CSRF attacks
• tenant_id (optional): Specific tenant to authenticate into

POST /connect/token

Exchanges an authorization code for access tokens, ID token, and optional refresh token.

Request Format: application/x-www-form-urlencoded

Parameters:

• grant_type (required): 'authorization_code', 'refresh_token', or 'password'
• code (required for auth code flow): Authorization code from /authorize
• client_id (required): Your application ID
• client_secret (required): Your application secret (keep confidential)
• redirect_uri (required): Must match the /authorize request
• code_verifier (required for SPA): PKCE code verifier
• refresh_token (for refresh flow): The refresh token to exchange
• username & password (for password flow): User credentials

POST /connect/introspect

Validates and inspects the contents of an access token or refresh token.

GET /.well-known/openid-configuration

Standard OIDC metadata endpoint. Returns discovery information including endpoints, public keys, supported scopes, and grant types.

Create a code verifier and challenge on the client side:

// 1. Generate random code verifier (43-128 characters)
const codeVerifier = generateRandomString(128);

// 2. Create code challenge via SHA256 hash
const codeChallenge = await crypto.subtle.digest('SHA-256',
  new TextEncoder().encode(codeVerifier)
);

// 3. Base64-URL encode the challenge
const codeChallengeB64 = base64UrlEncode(codeChallenge);

// Store codeVerifier in sessionStorage for Step 3
sessionStorage.setItem('pkce_verifier', codeVerifier);

Direct the user to sign in:

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &code_challenge={pkce_challenge}
  &state={random_state}

The user will be redirected to their identity provider (Microsoft, Google, or email/password), complete authentication, and be redirected back to your redirect_uri with an authorization code.

From your backend, exchange the authorization code:

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={auth_code}
&client_id={your_app_id}
&client_secret={your_app_secret}
&redirect_uri=https://your-app.com/callback
&code_verifier={pkce_verifier}

On success, you receive:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "DefxA1234567890...",
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Validate the ID token signature using the public key from /.well-known/openid-configuration, verify the issuer and audience claims, and extract user information.

The ID token (JWT) contains user identity information:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Key Claims:

• sub: Unique user identifier (Guid)
• email: User's email address
• email_verified: Whether email is verified
• name, given_name, family_name: User's name
• tenant_id: User's active tenant/organization
• iss: Token issuer (always https://api.advanza.ai)
• aud: Intended audience (your application ID)
• iat: Token issued at (Unix timestamp)
• exp: Token expiration (Unix timestamp)

The access token (JWT) contains authorization information:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "name": "John Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "roles": ["Owner"],
  "scope": "openid email profile offline_access roles",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Key Claims:

• sub: User ID
• email, name: User information
• tenant_id: Active tenant (use for multi-tenancy routing)
• roles: User's roles in the tenant
• scope: Granted scopes
• exp: Expiration (typically 1 hour)

Use Access Token For: Include in Authorization header (Authorization: Bearer {access_token}) when calling Advanza APIs or your backend.

On first sign-in, the user is assigned a default tenant. The tenant_id claim will be populated with this tenant's ID.

Users with multiple tenant memberships can switch tenants by passing the desired tenant_id parameter to the authorization endpoint:

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &tenant_id=12345678-1234-1234-1234-123456789012
  &code_challenge={pkce_challenge}

Use the tenant_id claim to route requests to the correct tenant context in your backend:

// Extract tenant from token claims
const tenantId = tokenClaims.tenant_id;

// Route request to tenant context
const tenantContext = getTenantContext(tenantId);
const result = await performAction(tenantContext, action);