Identity Provider (IdP) Configuration Repository

Overview

The IdpConfigRepository is a data access component responsible for persisting and retrieving Identity Provider (IdP) configurations. It manages settings for OIDC, SAML, and IAP providers on a per-tenant, per-installation basis, storing them in the s2r_idp_config database table.

This repository solves the problem of integrating the platform with external authentication providers. It acts as the canonical store for all connection details, such as client IDs, issuer URLs, and encrypted client secrets. Service-layer components call this repository to create, read, and update IdP settings, which in turn drive the platform's authentication and authorization mechanisms.

A key architectural concept is the platform's "authentication posture." The number of active IdP configurations for an entire installation determines whether the platform operates in "protected mode" (enforcing RBAC) or "open mode" (no authentication enforced). If at least one active IdP configuration exists for an installation, the platform is in protected mode. If there are zero, it falls back to open mode.

All operations are strictly tenant-scoped to ensure data isolation. The repository handles encrypted client secrets as opaque envelopes, with encryption and decryption being the responsibility of a higher-level service.

How it Works

The repository interacts with a single database table, s2r_idp_config. Its operations are designed to be atomic and preserve a complete audit history.

Tenancy and Security

Data access is strictly controlled by a multi-layered tenancy model:

1. Row-Level Security (RLS): The primary mechanism is the s2r_tenant_isolation policy on the s2r_idp_config table.
2. Explicit Scoping: Every read and deactivate operation explicitly includes a TENANT_SCOPE SQL clause. This ensures that even connections with RLS-bypassing privileges are correctly scoped to the application's current tenant.
3. Fail-Closed Connections: The TENANT_SCOPE includes a REQUIRE_BOUND_TENANT_SQL check. If a database connection is used without a tenant ID bound to it, the query will fail with an S2R-TENANCY-UNBOUND error rather than defaulting to another tenant's data or returning no data.
4. Tenant ID Fields:
   • The internal tenant_id column is automatically populated by the database based on the connection's settings during an INSERT.
   • The idp_directory_tenant_id field represents an external identifier for a tenant within the upstream IdP system and is distinct from the platform's internal tenant ID.

Upsert Logic

When creating or updating an IdP configuration via upsertActive or upsertIap, the repository follows a two-step process to ensure atomicity and maintain an audit trail. This prevents having more than one active configuration for a given provider.

sequenceDiagram
    participant Service as "Service Layer"
    participant Repo as "IdpConfigRepository"
    participant DB as "Database (s2r_idp_config)"

    Service->>Repo: upsertActive(installationId, provider, ...);
    Note over Repo: Begins upsert process

    Repo->>DB: UPDATE s2r_idp_config SET is_active = false WHERE installation_id = ? AND provider = ? AND is_active = true;
    Note right of DB: Deactivates any existing active config,<br/>preserving the row for audit.

    Repo->>DB: INSERT INTO s2r_idp_config (...) VALUES (...);
    Note right of DB: Inserts a new row with the new config,<br/>marked as is_active = true.

    DB-->>Repo: Returns new config's UUID
    Repo-->>Service: Returns new config's UUID

Deactivating a configuration via the deactivate method performs only the first step of this process. The old configuration remains in the database with is_active set to false.

Installation-Wide Auth Posture

The countActive method is an exception to the strict tenant-scoping rule. It calls a SECURITY DEFINER database function, s2r_idp_config_active_count, which intentionally reads across all tenants for a given installation. This is critical for determining the installation-wide authentication posture. If the count were tenant-scoped, a tenant without an IdP configuration could cause the entire installation to incorrectly switch to "open mode." This method returns only a count, never the configuration data of another tenant.

IAP Configuration

Identity-Aware Proxy (IAP) configurations are a special case. They are identified by the provider name iap.

• They do not use client secrets, issuer URLs, or other OIDC/SAML fields. Instead, their primary function is to manage an access list stored in iap_members.
• The upsertIap method creates these configurations. If an empty list is provided for iapMembers, the existing IAP configuration is deactivated, and no new active one is created. This effectively disables the IAP gate for the installation.

Repository Methods

The repository exposes the following methods for managing IdP configurations.

Data Structure: IdpConfigRow

This record represents a single row from the s2r_idp_config table.

Troubleshooting

S2R-TENANCY-UNBOUND Error

If a query fails with an error code of S2R-TENANCY-UNBOUND, it means a repository method was called using a database connection that did not have a tenant ID bound to it. This is a security feature to prevent accidental cross-tenant data access. Ensure the service calling the repository has properly established the tenant context on its database connection.

Null Arguments

Most methods perform null checks on their installationId and provider arguments. If a required identifier is null, the methods will typically return an empty result (e.g., List.of(), Optional.empty(), or 0) instead of throwing an exception.

IAP Deactivation

Calling upsertIap with a null or empty iapMembers list will deactivate the IAP gate for the installation. This is intentional behavior. If this was not the last active IdP for the installation, other IdP-based authentication will still be enforced. If it was the last active IdP, the installation may revert to "open mode."

See Also

• Auditing: Deactivated IdP configurations are preserved for auditing purposes. The deactivate and upsert methods update the is_active flag rather than deleting rows. This behavior is related to the system's AuditRepository.
• Credential Encryption: The clientSecretEnvelope field is handled by the CredentialsCipher service, which is responsible for all encryption and decryption operations. This repository only stores and retrieves the opaque, encrypted value.

All SOAP-to-REST docs