SSO Consumer Overview — SSO Consumers

What Is an SSO Consumer?

In the Passport ecosystem, your application is the consumer — it delegates authentication to Passport rather than handling credentials itself. Passport authenticates the user, issues tokens, and your application uses those tokens to establish identity and access rights.

The consumer pattern has two dimensions:

Outbound SSO (Login with External Provider)

Passport itself acts as a consumer when users log in with Google, Microsoft, or other external providers. The ISsoOrchestrationService handles the OAuth callback and provisions the user into Passport's database.

Inbound SSO (BizFirstGO Apps)

Your application uses Passport as the IdP. You configure an OIDC client, redirect users to Passport for authentication, and receive JWT access tokens. This is the primary pattern for BizFirstGO applications.

The OIDC Authorization Code Flow

BizFirstGO applications use the Authorization Code Flow with PKCE. This is the most secure OAuth 2.0 flow and is recommended for all client types — including SPAs and mobile apps.

User clicks "Sign In"

Your app generates a PKCE code_verifier, hashes it to code_challenge, generates a random state, and redirects the browser to /passport/authorize.

Passport authenticates the user

If no Passport session exists, the user is presented with the login form. If a session exists, this step is skipped (SSO). MFA is triggered if configured.

Callback with authorization code

Passport redirects to your registered callback URL with a short-lived code and the original state. Your app verifies the state matches.

Token exchange

Your backend (or BFF) exchanges the code for tokens by posting to /passport/token with the code_verifier. Receives access_token, id_token, refresh_token.

Use access token

Include the access token as a Bearer token in all API requests. Go.Essentials middleware validates the token and populates the IDInfo context.

Key Interfaces

// Core Passport consumer interfaces (Go.Essentials)
namespace BizFirst.Essentials.Passport;

// Validates a JWT access token issued by Passport
public interface IPassportTokenValidator
{
    Task<TokenValidationResult> ValidateAsync(string token, CancellationToken ct = default);
}

// Resolves the user's identity context from a validated token
public interface IPassportIdentityResolver
{
    Task<IDInfo?> ResolveAsync(ClaimsPrincipal principal, CancellationToken ct = default);
}

// Makes authorized calls to Passport APIs
public interface IPassportClient
{
    Task<bool> CheckPermissionAsync(string userId, string permission, string? resourceId = null, CancellationToken ct = default);
    Task<IReadOnlyList<string>> GetUserRolesAsync(string userId, CancellationToken ct = default);
}

Architecture Layers

Layer	Component	Responsibility
HTTP Controller	`SsoLoginController`	Handles `/api/sso/{provider}/login` and `/api/sso/{provider}/callback`
Orchestration	`ISsoOrchestrationService`	Authorization URL generation, callback processing, PKCE validation
Provider Routing	`ISsoGateway`	Routes to the correct `ISsoProvider` implementation by name
State Security	`ISsoStateManager`	HMAC-signed state parameter, replay protection, CSRF
Token Issuance	`IAuthenticationService`	Mints BizFirstGO JWTs after successful external authentication
DB Persistence	`IAM_ExternalIdentities`	Links external OAuth identities to BizFirst user accounts

Prerequisite: Guide1 — SSO Providers

This guide covers how applications consume Passport's SSO. You should first understand how Passport operates as an SSO Provider by reading Guide1: SSO Providers. In particular, OIDC client registration (Guide1, OIDC Provider page) is a prerequisite for this guide.

Next: OIDC Client Setup →