OAuth 2.0 & OpenID Connect

SingleSign is built on two complementary open standards: OAuth 2.0 for authorization and OpenID Connect (OIDC) for identity. Understanding how these protocols work together will help you make the right design decisions for your integration.

OAuth 2.0 — Authorization

OAuth 2.0 is an authorization framework that lets a user grant a third-party application limited access to their data without sharing their password.

Key Concepts

The Authorization Code Flow

SingleSign implements the Authorization Code flow, which is the most secure OAuth 2.0 flow for web and mobile applications:

┌────────────┐                         ┌──────────────────┐
│            │──1. Authorization Req──▶│                  │
│            │                         │                  │
│   User /   │◀─2. Login + Consent────│   SingleSign     │
│   Browser  │                         │   Authorization  │
│            │──3. Consent Grant──────▶│   Server         │
│            │                         │                  │
│            │◀─4. Auth Code──────────│                  │
└────────────┘                         └──────────────────┘
       │                                       ▲
       │                                       │
       ▼                                       │
┌────────────┐                                 │
│            │──5. Code + Verifier────────────▶│
│   Your     │                                 │
│   App      │◀─6. Tokens (access, id, refresh)│
│            │                                 │
└────────────┘                                 │

1. Your app redirects the user to SingleSign's /oauth/authorize endpoint.
2. SingleSign presents a login form and consent screen.
3. The user authenticates and approves the requested scopes.
4. SingleSign redirects back to your app with an authorization code.
5. Your app sends the code (plus PKCE verifier or client secret) to /oauth/token.
6. SingleSign returns an access token, ID token, and optionally a refresh token.

Why Not Implicit Flow?

The Implicit flow (response_type=token) delivers tokens directly in the URL fragment, exposing them to browser history and referrer leaks. SingleSign does not support the Implicit flow. Use Authorization Code with PKCE instead.

OpenID Connect — Identity

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0. While OAuth 2.0 tells you what a user can access, OIDC tells you who the user is.

What OIDC Adds

The ID Token

OIDC introduces the ID Token — a JWT that cryptographically asserts the user's identity. It includes:

• sub — Subject identifier (unique user ID).
• human_guid — SingleSign's unique user identifier (same value as sub).
• iss — Issuer (SingleSign).
• aud — Audience (your client_id).
• iat — Issued-at timestamp.
• exp — Expiration timestamp.
• Additional claims based on the requested scopes.

{
  "iss": "https://api.singlesign.com",
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "human_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "aud": "your-client-id",
  "iat": 1739996400,
  "exp": 1740000000,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "email_verified": true
}

What SingleSign Implements

SingleSign provides a complete OIDC-compliant authorization server:

Endpoints

Supported Features

• Authorization Code flow — The recommended and only supported grant type for user authentication.
• PKCE (S256) — Required for public clients, recommended for all clients.
• Token signing — JWTs are signed with HS512 (HMAC-SHA-512).
• Refresh tokens — Available when the offline_access scope is requested.
• OpenID Connect Discovery — Dynamic endpoint and capability discovery.
• Token introspection — RFC 7662-compliant token validation.
• Token revocation — RFC 7009-compliant token revocation.

Platform GUID

All SingleSign endpoints require a platform_guid query parameter that identifies your platform. This allows SingleSign to serve multiple isolated platforms from the same infrastructure.

https://api.singlesign.com/oauth/authorize?platform_guid=YOUR_PLATFORM_GUID&...

Discovery

The OpenID Connect Discovery endpoint lets your application automatically find all endpoints and supported features:

curl "https://api.singlesign.com/.well-known/openid-configuration?platform_guid=YOUR_PLATFORM_GUID"

Example response:

{
  "issuer": "https://api.singlesign.com",
  "authorization_endpoint": "https://api.singlesign.com/oauth/authorize",
  "token_endpoint": "https://api.singlesign.com/oauth/token",
  "userinfo_endpoint": "https://api.singlesign.com/oauth/userinfo",
  "jwks_uri": "https://api.singlesign.com/oauth/jwks",
  "introspection_endpoint": "https://api.singlesign.com/oauth/introspect",
  "revocation_endpoint": "https://api.singlesign.com/oauth/revoke",
  "scopes_supported": ["openid", "profile", "email", "phone", "address", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "id_token_signing_alg_values_supported": ["HS512"],
  "subject_types_supported": ["public"]
}

Use this response to configure your client dynamically instead of hard-coding endpoint URLs.

JWKS — Key Verification

The JSON Web Key Set (JWKS) endpoint provides the public keys used to verify token signatures:

curl "https://api.singlesign.com/oauth/jwks?platform_guid=YOUR_PLATFORM_GUID"

Libraries like jose (JavaScript), PyJWT (Python), or java-jwt (Java) can fetch and cache these keys automatically.

Next Steps

• PKCE — Understand the Proof Key for Code Exchange mechanism.
• Tokens & Claims — Decode and verify your JWTs.
• Endpoint Reference — Full API documentation.
• Quickstart Guide — Build your first integration.