auth

Auth Package

The auth package provides modular authentication strategies for the remote client.

Authenticator Interface

All strategies implement the Authenticator interface, allowing them to be easily injected into any remote.Client.

type Authenticator interface {
    Apply(req *http.Request) error
}

Construction

There are two ways to build an authenticator:

1. From config — auth.Build(authType, options) parses the JSON options for a strategy, resolves any secret references (see Secret References) once, and returns the authenticator. This is what the remote Manager uses when it loads services.json. A reference that cannot be resolved is a loud error.

   authn, err := auth.Build("oauth2", optionsJSON)
   

2. Directly — the New* constructors take already-resolved plain values. They are pure: no I/O, no error.

   auth.NewAPIKey("X-Custom-Key", "my-secret-key")
   auth.NewBearer("my-jwt-token")
   auth.NewOAuth2("https://identity.example.com/oauth2/token", "my-client-id", "my-client-secret", []string{"read", "write"})
   

Supported Strategies

API Key Authentication

Uses a custom header (e.g., X-API-Key) with a fixed value.

Bearer Token Authentication

Uses the standard Authorization: Bearer <token> header.

OAuth2 Client Credentials Flow

Implements the OAuth2 Client Credentials flow with the following features:

• Automatic token caching.
• Expiry handling with a 1-minute safety buffer.
• Synchronized token updates to prevent race conditions.
• Scope support.

Secret References

Secret-bearing config fields (value, token, client_secret) are a secret.SecretRef — a literal value or a scheme-prefixed reference (env:NAME, file:/path) that is resolved to its concrete value. The type lives in the standalone secret module; see its README for the full scheme table and how to add a source.

In services.json, a reference is written per field:

{
  "auth": {
    "type": "oauth2",
    "options": {
      "token_url": "https://identity.example.com/oauth2/token",
      "client_id": "my-client",
      "client_secret": "env:CLIENT_SECRET",
      "scopes": ["read", "write"]
    }
  }
}

References are resolved once, at startup — when Manager.LoadServices loads the file, or via auth.Build. A missing env var or an unreadable/empty file is a loud error — a reference never silently resolves to the empty string. Resolution is not repeated per request; if a referenced value changes, restart the process to pick it up.

Strategy Configuration

APIKeyConfig

Used when the authentication type is "api_key".

BearerConfig

Used when the authentication type is "bearer".

OAuth2Config

Used when the authentication type is "oauth2".

{
  "token_url": "https://idp.example/oauth2/token",
  "client_id": "my-client",
  "client_secret": "env:MY_CLIENT_SECRET",
  "scopes": ["api:read"],
  "endpoint_params": { "resource": "https://api.example" }
}