Enterprise SSO Architecture (Federation & Keycloak Alternative)

SCRIPE is built as a complete Enterprise Identity and Access Management (IAM) Server relying on OpenIddict. It handles both sides of the SSO equation: First, as a federated Identity Provider (Client) connecting to Google/Azure AD, and Second, as an OAuth2/OIDC Authorization Server replacing Keycloak.

Massive IAM Capabilities

• Global & Per-Tenant External Identity Providers

  Federate instantly with external OIDC/OAuth2 providers (Google, Azure AD, Okta, AWS Cognito). SuperAdmins can configure Global providers for all users, while Tenant Admins can bind their own isolated Corporate Azure AD or Workspace directly from the Admin Panel, enabling zero-code B2B SSO setups.

• SCRIPE as the Identity Server

  Replace Keycloak entirely. Register third-party business systems, mobile apps, and external dashboards directly into SCRIPE via the Admin Panel. Issue Client IDs and Secrets, control scopes, and generate enterprise-grade JWTs backed by SCRIPE's identity store.

• Strict PKCE & Zero-Code Config

  The deprecated Implicit Flow is eradicated. All authentication is strictly enforced via Proof Key for Code Exchange (PKCE). Easily toggle integrations on or off, define claim mapping rules, and manage secrets without touching a single line of backend code.

• Multi-Tenant Realm Isolation

  Every tenant is an isolated IAM realm. If Tenant A connects to their Corporate Azure AD, Tenant B has absolutely no visibility. Tenant A issues credentials to its own OAuth apps without polluting the global root infrastructure.

IAM Setup Guide (Admin Panel)

Configuring SCRIPE as your primary authentication gateway via the Admin UI:

1. 1

   1. Bind an External Identity Provider (Client Mode)

   Navigate to `/settings/identity-providers`. Enter the Discovery/Authority URL, Client ID, and Secret from Azure AD or Google. You can mark this provider as 'Global' (all tenants) or bind it to your specific Tenant.
2. 2

   2. Automatic Claim Mapping

   Configure requested scopes (openid, profile, email). SCRIPE automatically maps external JWT claims (like `preferred_username`, `picture`, `given_name`) to internal Admin/User profiles, enabling Just-In-Time (JIT) provisioning instantly.
3. 3

   3. Enforce IAM Policies

   Decide whether the provider is for Admins (back-office) or Users (front-office). Identity bindings are strictly typed—preventing an external User from escalating into an Admin session.
4. 4

   4. Register Third-Party Apps (Server Mode)

   Navigate to `/settings/oauth-apps` to make SCRIPE the SSO provider for external software (e.g., your custom mobile app). Define Public (SPA) or Confidential (Backend) profiles entirely via the UI.
5. 5

   5. Jwks Uri & Discovery

   External applications simply point their Authority to `https://your-scripe-instance.com`. SCRIPE automatically serves the `/.well-known/openid-configuration` and `/.well-known/jwks` discovery endpoints.

IAM Control Center Settings

The Admin Panel provides two dedicated control centers for IAM: Identity Providers (for inbound federation) and OAuth Applications (for outbound authorization server capabilities).

The Decoupled OIDC Architecture

SCRIPE cleanly separates the protocol handshake from the UI login form. When acting as a Relying Party to Azure AD, SCRIPE redirects the user, accepts the callback, validates the external JWT, and then issues its OWN internal JWT, completely decoupling internal authorization from the external provider.

1. User navigates to /login — the login page automatically fetches available SSO providers
2. If providers exist, branded SSO buttons appear below the sign-in form with an 'or continue with' divider
3. User clicks a provider button → frontend calls POST /auth/oidc/challenge → gets authorization URL with PKCE parameters
4. PKCE state (code_verifier, state, providerId) is stored in sessionStorage — frontend redirects to the IdP
5. User authenticates at the external IdP (Azure AD, Google, etc.) and grants consent
6. IdP redirects back to /sso/callback?code=...&state=...
7. Callback page retrieves PKCE state from sessionStorage, validates state matches (CSRF protection)
8. Frontend calls POST /auth/oidc/callback with code + codeVerifier → backend exchanges code for user info
9. Backend finds the linked ExternalLogin record → returns the admin/user identity
10. Frontend completes login: stores auth tokens, loads navigation, redirects to dashboard

Realm (Tenant) Partitioning

SCRIPE matches Keycloak's Realm concept perfectly through Tenant Partitions. Identity Providers and OAuth Applications are strictly bound to their TenantId. SuperAdmins manage all realms via the 'Enter Tenant World' capability.

SAML 2.0 & Cryptographic Assertion Security

In addition to OIDC, the platform integrates SAML 2.0 authentication using the ITfoxtec.Identity.Saml2 library. For inbound SSO, public X.509 certificates are loaded from base64 string configurations to validate SAML response signatures while ignoring certificate chain validations. Outbound client connections use platform-wide signing certificates to issue secure SAML assertions.

OIDC Callback & Workspace Caching Flow

The callback handler validates incoming credentials and manages workspace selection for administrators with access to multiple tenants. A temporary token caches the login profile (SsoTempLoginData) in Redis for 15 minutes, allowing safe workspace selection in the frontend without transferring raw user variables.

OAuth Application Mirroring & Subscription Quotas

Administrators can register custom client applications to use SCRIPE as their primary OIDC server. New application creations are gated by tenant-scoped quotas. Once validated, client details are registered in OpenIddict and mirrored locally in the platform's OAuthApplication database table for fast performance, masking confidential client secrets.