Postal with a
provisioning API

What this fork adds

Configuration

Add to postal.yml. Postal fetches IdP public keys automatically via JWKS — no signing secret stored locally.

Single provider (legacy / simple setup)

api:
  enabled: true
  required_azp: postal-api          # optional — restrict to one specific KC client

oidc:
  enabled: true
  name: "Login with Keycloak"
  issuer: https://login.example.com/realms/myrealm  # must match 'iss' in your JWTs
  identifier: postal                # OAuth2 client_id — required for the SSO login button
  secret: <client_secret>          # required for the SSO login button; omit if API-only
  # jwks_uri: ...                   # override; auto-discovered from issuer by default
  auto_create_org_on_signup: true
  auto_provision_org: false
  auto_create_user: true            # false = SCIM-only: unknown identities rejected at login (no JIT account creation)

scim:
  enabled: true
  bearer_token: <scim-static-token>

Multiple providers

Use the oidc.providers array to register several IdPs. Each gets its own login button, JWKS cache, and discovery document.

oidc:
  enabled: true
  providers:
    - id: keycloak
      display_name: "Login with Keycloak"
      issuer: https://login.example.com/realms/myrealm
      identifier: postal
      secret: <client_secret>
      scopes: [openid, email]

    - id: entra
      display_name: "Login with Microsoft"
      issuer: https://login.microsoftonline.com/<tenant_id>/v2.0
      identifier: <app_id>
      secret: <app_secret>
      scopes: [openid, email, profile]

    - id: google
      display_name: "Login with Google"
      issuer: https://accounts.google.com
      identifier: <client_id>.apps.googleusercontent.com
      secret: <client_secret>

identifier / secret are only required for the SSO login button (Authorization Code flow). For API JWT verification and BCL, Postal only needs issuer (public JWKS). Omit them if the provider is used for token validation only.

Authentication

Postal is a Resource Server only — it never issues tokens. Your IdP (Keycloak, Microsoft Entra, Google) issues JWTs; Postal verifies them via JWKS, auto-discovered from {issuer}/.well-known/openid-configuration and cached 1 h. On key rotation, the cache busts automatically on the next unknown kid.

Authorization: Bearer <access_token>

Token types & access level

User identity is resolved from the JWT email or preferred_username claim, matched against User.email_address.

Keycloak — service account (super-admin)

Realm → Clients → Create client: set Client authentication ON, Service accounts roles ON.

curl -s -X POST \
  https://login.example.com/realms/myrealm/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=postal-api \
  -d client_secret=<secret> | jq -r .access_token

Keycloak — user token (org-admin / member / readonly)

Standard authorization_code flow or, for testing, the password grant (if enabled in realm):

curl -s -X POST \
  https://login.example.com/realms/myrealm/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=postal-ui \
  -d username=alice@example.com \
  -d password=<password> | jq -r .access_token

Microsoft Entra

curl -s -X POST \
  https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token \
  -d grant_type=client_credentials \
  -d client_id=<app_id> \
  -d client_secret=<secret> \
  -d scope=<app_id>/.default | jq -r .access_token

oidc:
  issuer: https://login.microsoftonline.com/<tenant_id>/v2.0
api:
  required_azp: <app_id>

Google

# Using oauth2l
oauth2l fetch --credentials service-account.json --scope openid email

oidc:
  issuer: https://accounts.google.com
api:
  required_azp: <client_id from service-account.json>

API v2 reference

Base URL: https://postal.example.com/api/v2. All requests need Authorization: Bearer <token> and Content-Type: application/json on writes.

Pagination: ?page=1&per_page=50 (max 200). Errors: {"errors": ["Name can't be blank"]} or {"error": "forbidden"}.

Organizations

curl https://postal.example.com/api/v2/organizations \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://postal.example.com/api/v2/organizations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme",
    "permalink": "acme",
    "time_zone": "UTC",
    "owner_email": "admin@acme.com",
    "skip_default_server": false
  }'

curl https://postal.example.com/api/v2/organizations/acme \
  -H "Authorization: Bearer $TOKEN"

curl -X PATCH https://postal.example.com/api/v2/organizations/acme \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "time_zone": "Europe/Paris"}'

curl -X DELETE https://postal.example.com/api/v2/organizations/acme \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://postal.example.com/api/v2/organizations/acme/suspend \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Payment overdue"}'

# Unsuspend
curl -X POST https://postal.example.com/api/v2/organizations/acme/unsuspend \
  -H "Authorization: Bearer $TOKEN"

Members

curl https://postal.example.com/api/v2/organizations/acme/members \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://postal.example.com/api/v2/organizations/acme/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "auditor@acme.com", "role": "readonly"}'

curl -X PATCH https://postal.example.com/api/v2/organizations/acme/members/auditor@acme.com \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "member"}'

curl -X DELETE https://postal.example.com/api/v2/organizations/acme/members/auditor@acme.com \
  -H "Authorization: Bearer $TOKEN"

Servers

curl https://postal.example.com/api/v2/organizations/acme/servers \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://postal.example.com/api/v2/organizations/acme/servers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "permalink": "production", "mode": "Live"}'

curl -X PATCH https://postal.example.com/api/v2/organizations/acme/servers/production \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"send_limit": 5000, "message_retention_days": 30}'

curl -X DELETE https://postal.example.com/api/v2/organizations/acme/servers/production \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://postal.example.com/api/v2/organizations/acme/servers/production/suspend \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"reason": "Abuse detected"}'

curl -X POST .../unsuspend -H "Authorization: Bearer $TOKEN"

Domains

curl -X POST https://postal.example.com/api/v2/organizations/acme/servers/production/domains \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "mail.acme.com"}'

curl -X POST https://postal.example.com/api/v2/organizations/acme/servers/production/domains/<uuid>/verify \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://postal.example.com/api/v2/organizations/acme/servers/production/domains/<uuid>/dns_check \
  -H "Authorization: Bearer $TOKEN"

Credentials

curl -X POST https://postal.example.com/api/v2/organizations/acme/servers/production/credentials \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "App mailer", "type": "SMTP"}'

# Response:
# { "id": "...", "name": "App mailer", "type": "SMTP", "key": "smtp+login://...", ... }

curl https://postal.example.com/api/v2/organizations/acme/servers/production/credentials \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE https://postal.example.com/api/v2/organizations/acme/servers/production/credentials/<uuid> \
  -H "Authorization: Bearer $TOKEN"

Users

curl "https://postal.example.com/api/v2/users?page=1&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://postal.example.com/api/v2/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alice",
    "last_name": "Smith",
    "email_address": "alice@acme.com",
    "time_zone": "UTC",
    "password": "hunter2"
  }'

curl -X PATCH https://postal.example.com/api/v2/users/alice@acme.com \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Alicia"}'

curl -X DELETE https://postal.example.com/api/v2/users/alice@acme.com \
  -H "Authorization: Bearer $TOKEN"

SCIM v2 — per-tenant

All SCIM endpoints are namespaced per org: /scim/v2/tenants/:org_permalink/…. Auth: static Authorization: Bearer <scim.bearer_token>.

Users

# Create user in org with member role
curl -X POST https://postal.example.com/scim/v2/tenants/acme/Users \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "bob@acme.com",
    "name": { "givenName": "Bob", "familyName": "Jones" },
    "emails": [{ "value": "bob@acme.com", "primary": true }],
    "role": "member"
  }'

Groups (= the org)

In this model, one org = one SCIM group. The group is the org — there are no sub-groups or teams within an org. Postal has no sub-group concept: roles (admin, member, readonly) are set directly on the user↔org link. If you need separate access scopes, create one org per scope and provision users into each.

No POST or DELETE — org lifecycle is managed via API v2. PATCH handles org attributes and members in one request.

# Update org name + add a member + change a role in one request
curl -X PATCH https://postal.example.com/scim/v2/tenants/acme/Groups/42 \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "displayName": "Acme Corporation",
    "urn:postal:1.0:org": { "time_zone": "Europe/Paris" },
    "Operations": [
      { "op": "add",    "path": "members", "value": [{ "value": "alice@acme.com", "role": "admin" }] },
      { "op": "remove", "path": "members", "value": [{ "value": "old@acme.com" }] }
    ]
  }'

urn:postal:1.0:org extension fields

Member roles

Roles are enforced on both the API v2 and the web UI. readonly users see everything but cannot write.

SSO / OIDC provisioning

Disable local (password) login

Set oidc.local_authentication_enabled: false to force SSO-only access. When disabled:

• The email/password form is hidden from the login page
• POST /login, password reset requests and password reset flows are all blocked server-side (403)
• Only the Login with {provider} button remains
• Users with no SSO identity can no longer log in — ensure all users are in your IdP before enabling this

oidc:
  enabled: true
  issuer: https://login.example.com/realms/myrealm
  local_authentication_enabled: false   # SSO only, no password login

JIT user provisioning

When a user logs in via SSO and does not exist in Postal, they are automatically created (JIT provisioning). Name and email are read from the JWT claims (given_name, family_name, email).

Auto-create org on signup

Enable oidc.auto_create_org_on_signup: true. When a brand-new user is JIT-provisioned, Postal automatically creates an org named after their preferred_username (or email prefix if absent). The slug is parameterized and deduplicated if taken.

oidc:
  auto_create_org_on_signup: true

# alice.smith@example.com logs in for the first time
# → user created
# → org "alice-smith" created (Live SMTP server + default credential auto-provisioned)
# → alice is org admin

Org provisioning from JWT claim

Enable oidc.auto_provision_org: true. On every login, Postal reads the organization claim and creates/joins the org:

# JWT claim — Keycloak can send a custom claim:
"organization": { "acme": { "name": "Acme Corp" } }
# or as array:
"organization": ["acme", "beta-corp"]

Both options can be active at the same time: auto-create on first login + sync from claim on every login.

Back-Channel Logout (BCL)

When a user logs out of the IdP (or is force-logged-out), the IdP POSTs a signed logout_token to Postal. Postal validates the RS256 signature against the provider's JWKS, then invalidates all active Postal sessions for that user.

Endpoint: POST /auth/oidc/backchannel_logout (no authentication header required — the logout_token itself is the proof).

Configure in Keycloak: Realm → Clients → your client → Advanced → Backchannel logout URL:

https://postal.example.com/auth/oidc/backchannel_logout

Enable Backchannel logout session required so Keycloak always includes sid and sub in the logout_token.

With multiple providers, the single endpoint handles all of them — Postal identifies the provider from the iss claim and picks the right JWKS.

RP-Initiated Logout (redirect logout)

When a user clicks Sign out in Postal, if a Keycloak id_token is present in the session, Postal redirects to the IdP's end_session_endpoint with:

• id_token_hint — the user's original id_token
• post_logout_redirect_uri — Postal's login page
• state — random nonce for CSRF protection

The IdP then terminates the SSO session and redirects back to the Postal login page. If the provider does not expose an end_session_endpoint in its discovery document, Postal falls back to a local session invalidation only.

Configure in Keycloak: Realm → Clients → your client → Advanced → Valid post logout redirect URIs:

https://postal.example.com/login