SSO Authentication Flow

This guide covers the Single Sign-On (SSO) integration using OAuth 2.0 and OpenID Connect (OIDC). The boilerplate supports robust integration with identity providers like Google and GitHub.

Architecture Overview

The SSO flow is completely built into the core domain layer (src/domain/sso), avoiding heavy framework coupling and using the clean distinction between Identities and Credentials.

Press enter or space to select a node. You can then use the arrow keys to move the node around. You can then use the arrow keys to move the node around, press delete to remove it and press escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or press escape to cancel.

Key Components

1. get-authorize.ts (The Redirect)

The entrypoint /authorize generates the necessary URL to redirect the user to the provider.

• It includes security measures such as state generation to prevent CSRF attacks.
• Certain providers, such as Google, might also require a nonce depending on the requested response_type.

2. get-callback.ts (The Token Exchange & Login)

Once the IDP redirects the user back to the application (/callback), this controller:

• Extracts the authorization code from the query string.
• Validates the state to ensure the session wasn't hijacked.
• Calls the underlying exchangeToken infrastructure to swap the code for an access_token (and id_token if applicable).
• Generates or updates the internal Identity and Credential.
• Finally, it provides the internal JWT used by the application for subsequent requests.

3. oidc.ts (The Infrastructure Hook)

Located at src/infrastructure/sso/oidc.ts, this file manages all the external communication with the providers:

• exchangeToken: Hits the provider's token endpoint to trade codes.
• verifyIdToken: A robust built-in JWT validator that fetches the provider's Public Keys (JWKS), verifies the kid (Key ID), and ensures the exp (Expiration) and signature are completely valid before trusting the token.
• getNormalizedUser: Maps different API contracts (e.g. Google's parsed id_token vs GitHub's /user endpoint) into a consistent format.

Environment Configuration

To enable SSO, setup the specific environment variables in your .env:

# Google SSO
SSO_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
SSO_GOOGLE_CLIENT_SECRET="your-client-secret"
SSO_GOOGLE_REDIRECT_URI="http://localhost:3000/api/v1/sso/callback"

# GitHub SSO
SSO_GITHUB_CLIENT_ID="your-client-id"
SSO_GITHUB_CLIENT_SECRET="your-client-secret"
SSO_GITHUB_REDIRECT_URI="http://localhost:3000/api/v1/sso/callback"

NOTE

If a provider is not configured, the boilerplate will instantly throw an error if a user attempts to use /authorize for that provider.

Security Considerations

1. The OAuth flow uses JWKS validation arrays to ensure id_tokens received from providers like Google belong to them and weren't tampered with.
2. We enforce state comparison across both GitHub and Google to guarantee CSRF resistance.
3. Access tokens inside the application are extremely short-lived, favoring refresh tokens.