Skip to content

Push users from Kevra to a downstream app (outbound SCIM)

Time: ~10 min · Prereqs:

  • Admin access to your Kevra Identity tenant in the Kevra console
  • A downstream application that exposes a SCIM 2.0 endpoint
  • The downstream's SCIM base URL and a bearer token it accepts

What you'll set up

When a user is created, updated, enabled, or disabled in your Kevra realm, Kevra POSTs or PATCHes that change to a downstream SCIM 2.0 application. Use this when a SaaS app you operate consumes user lifecycle from Kevra rather than from your IdP directly.

Before you begin

Verify the downstream endpoint is reachable and accepts your token. From any host that can reach it:

bash curl -H "Authorization: Bearer DOWNSTREAM_TOKEN" \ https://downstream.example.com/scim/v2/ServiceProviderConfig

You should get a JSON document describing supported features. If you get HTML, 404, or 401, fix the downstream side first.

Step 1: Enable outbound SCIM in the Kevra console

  1. In the Kevra console, open your Identity tenant detail page.
  2. Scroll to Identity sync (SCIM 2.0).
  3. In the Outbound SCIM panel, fill the form:
    • Downstream SCIM base URL: e.g. https://downstream.example.com/scim/v2
    • Downstream bearer token: the token the downstream expects
  4. Click Enable outbound SCIM.
  5. The status badge changes to Enabled and the panel shows the configured downstream endpoint.

Step 2: Trigger your first push

Outbound activates immediately. Subsequent changes to users in your realm fire pushes:

Change in Kevra Downstream call
Create user POST /Users
Update profile (name, email) PATCH /Users/USER_ID
Disable user (enabled=false) PATCH /Users/USER_ID with active=false
Re-enable user PATCH /Users/USER_ID with active=true
Delete user not propagated (see Limitations)

To force a first push, click Open Admin Console on the tenant page, open any user, toggle their Enabled state off and on, and save. The downstream should receive a PATCH /Users/USER_ID.

Step 3: Verify the downstream received the push

  1. In the downstream app, find the user you just touched in Kevra.
  2. Confirm the externalId on the downstream record matches the user's UUID in Kevra (visible in the realm admin console).
  3. Make a second change in Kevra (for example, update last name in the realm admin console). Confirm the downstream record updates within seconds.

If you control the downstream service, tail its access log. You should see entries like:

text POST /scim/v2/Users 201 PATCH /scim/v2/Users/USER_UUID 200

Disabling or rotating outbound

In the Kevra console, on the same tenant detail page:

  • Disable outbound: click Disable in the Outbound SCIM panel. The component is removed from your realm and lifecycle events stop propagating to the downstream. The form reappears, ready to be re-configured if needed.
  • Rotate the downstream token (the one the downstream expects from Kevra): click Disable, then re-enable the panel with the new token in the bearer token field.

Limitations

  • Hard deletes are not propagated. Deleting a user in your Kevra realm does not send a DELETE /Users/USER_ID to the downstream. Disable the user instead (enabled=false); the resulting active=false PATCH does propagate. This matches how real IdPs handle lifecycle (deactivation-driven, not deletion-driven).
  • Initial backfill is not automatic. Existing users in your realm before outbound was enabled are not retroactively pushed. To force a backfill, touch each user manually (toggle disabled on/off in the realm admin console).
  • One downstream per tenant. The Kevra console wires a single outbound SCIM target per tenant. Contact us if you need to push to multiple downstream SCIM apps from one realm.

Troubleshooting

Enable returns an error in the Kevra console The most common cause is a downstream URL that returns 404 or 401 on GET /ServiceProviderConfig. Re-test with curl from outside Kevra (see Before you begin) and fix the downstream side, then retry.

Downstream returns 401 on every push The bearer token is wrong, expired, or rotated by the downstream. Generate a new token on the downstream, then click Disable in the Outbound SCIM panel and re-enable with the new token.

Downstream returns 409 Conflict on POST A user with the same userName or externalId already exists on the downstream. Reconcile manually, then retry by editing the user in Kevra.

Pushes stop firing after a Keycloak restart Rare. Click Disable then re-enable to re-register the listener.

Next steps