API Documentation

Complete reference for AGG Labs SSO OAuth 2.0 and OpenID Connect implementation

This document outlines the endpoints provided by the centralized SSO Identity Provider (IdP). The system implements the OAuth 2.0 Authorization Code Flow with PKCE and OpenID Connect (OIDC) standards.

Core Concepts

Global Session: Maintained by the IdP via an HttpOnly, Secure cookie (sso_session). Enables Silent SSO across multiple Service Providers (SPs).
PKCE (Proof Key for Code Exchange): Mandatory security extension preventing authorization code interception. Requires code_challenge (S256) on authorization and code_verifier on token exchange.
Token Rotation: Refresh tokens are opaque, one-time use, and immediately rotated upon usage to prevent Replay Attacks.

1. Discovery & Cryptography

GET /.well-known/jwks.json

Returns the JSON Web Key Set (JWKS) containing the public keys used by the IdP to sign JWTs (id_token and access_token). Service Providers use this endpoint to verify token signatures offline.

Request Headers: None

Query Parameters: None

Response (200 OK)

{
  "keys": [
    {
      "kty": "RSA",
      "n": "...",
      "e": "AQAB",
      "alg": "RS256",
      "kid": "sso-key-v1",
      "use": "sig"
    }
  ]
}

2. Authorization Flow

GET /authorize

Initializes the OIDC flow. Validates the client and checks for an existing global SSO session. If a valid session exists (Silent SSO), it immediately redirects back with an authorization code. Otherwise, it redirects to the login page.

Query Parameters

response_type (string, required): Must be code.
client_id (string, required): The ID of the Service Provider.
redirect_uri (string, required): Registered callback URL of the Service Provider.
code_challenge (string, required): Base64URL-encoded SHA-256 hash of the code verifier.
code_challenge_method (string, required): Must be S256.
state (string, required): Random string generated by SP to maintain state.
scope (string, optional): Requested scopes (e.g., openid profile email).

Responses

302 Found (No Session): Redirects to /login forwarding all query parameters.
302 Found (Active Session): Redirects to redirect_uri appending ?code={auth_code}&state={state}.
400 Bad Request: If client_id is invalid or redirect_uri does not match.

GET /login

Renders the HTML login interface. This endpoint is accessed via redirection from /authorize.

Query Parameters: Inherits client_id, redirect_uri, code_challenge, and state from the authorize request.
Response (200 OK): HTML document containing the login form with hidden inputs for OIDC state propagation.

POST /login

Processes user credentials. On success, it creates a global SSO session cookie and issues a short-lived authorization code.

Content-Type: application/json (or form data depending on frontend implementation)

Request Body

email (string, required): User's email.
password (string, required): User's raw password.
client_id, redirect_uri, code_challenge, state (strings, required): OIDC parameters.

Responses

302 Found (Success): Sets sso_session cookie. Redirects to SP's redirect_uri with code and state.
401 Unauthorized: Invalid email or password.
400 Bad Request: Missing parameters.

3. Token Management

POST /token

Exchanges an authorization code for tokens, or refreshes an existing token set using a refresh token.

Content-Type: application/x-www-form-urlencoded

Flow A: Auth Code Exchange

grant_type: authorization_code
client_id: (string) SP identifier.
redirect_uri: (string) Must match URI.
code: (string) Received auth code.
code_verifier: (string) Original unhashed string.

Flow B: Refresh Token Rotation

grant_type: refresh_token
client_id: (string) SP identifier.
refresh_token: (string) The active refresh token.

Response (200 OK)

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "opaque_string_here...",
  "id_token": "eyJhbGci..."
}

Error Responses (400 Bad Request)

{"error": "invalid_grant"}: Code expired, already used, or PKCE verification failed.
{"error": "invalid_request"}: Malformed request body.

4. User Profile

GET /userinfo

Returns claims about the authenticated end-user. The endpoint is protected by the access_token.

Request Headers: Authorization: Bearer <access_token>

Response (200 OK)

{
  "sub": "931a43b0-8282-4f46-9576-12ec1ea99c53",
  "email": "[email protected]",
  "email_verified": true
}

Error Responses

401 Unauthorized: Token is missing, expired, or cryptographically invalid.
404 Not Found: User ID extracted from the token no longer exists in the database.

5. Session Management & Revocation

POST /logout

Terminates the global SSO session for the user across all applications.

Request Headers: Must include the sso_session cookie.
Response (200 OK): Instructs the browser to clear the sso_session cookie.

Returns: {"message": "Successfully logged out"}

POST /revoke

Implements RFC 7009. Allows a Service Provider to invalidate an active refresh token.

Content-Type: application/json

Request Body

token (string, required): The refresh token to be revoked.
client_id (string, required): Validates that the SP requesting revocation is the owner.

Response (200 OK)

Returns an empty JSON object {}. It always returns 200 OK regardless of whether the token existed or not, preventing token enumeration attacks.