Skip to main content

0008: IAM Service Service-to-Service (S2S) Authentication

Date: 2025-08-03

Status: Accepted

Context​

While most administrative actions in the iam-service (e.g., updating a tenant, assigning a role) are performed on behalf of an authenticated end-user, there are specific system-level interactions where no user is present. For example, an internal service may need to query the upstream IdP for user information in bulk.

These machine-to-machine interactions require a secure authentication mechanism that is distinct from the user-based token flow.

Decision​

We will use the OAuth 2.0 Client Credentials Flow for specific, system-level S2S communication.

  1. Limited Scope: S2S authentication is only to be used for endpoints that do not involve an end-user's context. A primary example is the /api/iam/v1/system/users/query endpoint, which is used by the admin-bff to look up user details from the upstream IdP.

  2. User-Context for Admin CRUD: All standard administrative CRUD operations (e.g., PUT /tenants/:id, PATCH /admin/users/:id) are not S2S. They are performed on behalf of an authenticated administrator, and the admin-bff must forward the user's original access token for these requests. The iam-service relies on the user's roles within that token to perform authorization checks.

  3. Mechanism: Each internal service that needs to make an S2S call will be registered as a "machine client" in our Identity Provider (IdP). This client will be issued a Client ID and a Client Secret. To make an authenticated request, the client service will first request a short-lived access token from the IdP's token endpoint using its credentials. This token will then be included in the Authorization header of the request to the iam-service.

  4. Authorization: The iam-service will have a dedicated M2MAuthorization middleware responsible for validating the S2S token. Authorization will be handled by checking that the scope claim within the validated token contains a specific, required scope (e.g., s2s:internal).

Consequences​

Positive:​

  • Standard-Based Security: Leverages a mature and well-understood industry standard (OAuth 2.0) for S2S security.
  • Centralized Control: All client services are managed within the central IdP, providing a single place to grant, revoke, and audit access.
  • Clear Separation: The distinction between user-driven administrative actions and system-level S2S calls is now explicit and enforced by different middleware.
  • Decoupling: Services do not need to know each other's internal secrets; they only need to trust the IdP.

Negative:​

  • Dependency on IdP: All S2S calls will have a dependency on the IdP's availability to issue tokens.
  • Slight Latency: There is a minor performance overhead for the initial S2S token request, though this can be mitigated by caching the token until it expires.