
# SCIM without the pain

If you sell to enterprises, you're going to hear the acronym **SCIM** a lot. SCIM (System for Cross-domain Identity Management) is the standard IdPs (Okta, Entra/Azure, OneLogin, etc.) use to _provision and deprovision users automatically_.

Someone joins their company? They're added to your app. They leave? Access is revoked. It's clean, auditable, and it keeps your customer's IT team happy.

The catch: implementing SCIM from scratch means juggling many endpoints, subtle differences between each IdP (like Entra sending strings instead of booleans depending on when the account was created), and long feedback loops with customer admins.

That's exactly why we built SCIM into **PropelAuth BYO**.

## Why SCIM in BYO feels different

### One route to rule them all

The SCIM spec defines a handful of endpoints (`/Users`, `/Groups`, `/Schema`, etc.) that you'll need to implement. Each one has its own quirks and edge cases, and different IdPs behave differently.

With BYO you stand up a single **catch-all** route (e.g. `/api/scim/*`) and forward requests to the sidecar. We parse the request and tell you if an action is required (like **LinkUser** on first-time provisioning, allowing you to provide your own ID or reject the request, or **DisableUser** on deprovision). If there's no action required, we hand back a response body + status that you can return directly to the IdP. You keep control of your data model without building the whole spec.

![diagram of how BYO handles SCIM requests](/images/blog/2025-10-02-scim-but-better/simplify.png)

### You define the data you want (and how it's mapped)

Let's say you want to collect a custom attribute from your customer like `favorite_sport`. Where does that live in the SCIM payload?

Unfortunately, while the SCIM spec defines a core schema, it's not as prescriptive when it comes to custom attributes (and the folks that wrote the SCIM spec didn't think about how important the `favorite_sport` field would be to your business).

BYO lets you **declare the schema you want** and map incoming IdP fields to it. For example, to capture a user's favorite sport, we define the property in our schema:

```json
{
    "userSchema": [
        // ...
        {
            "outputField": "favorite_sport",
            "inputPath": "favoriteSport",
            "displayName": "Favorite Sport",
            "description": "The user's favorite Sport",
            "propertyType": {
                "dataType": "String"
            }
        }
    ]
}
```

Once mapped, whenever SCIM requests arrive, BYO will look for `favoriteSport` in the incoming payload, extract it, and store it under `favorite_sport` in its normalized view of the user. That means that property is available both in SCIM request handling and when you ask for a user later via `getScimUser`.

In other words: you will always get a normalized shape from the sidecar.

Oh, and it works retroactively as well. So you can update your mappings at any time and calls to `getScimUser` will reflect the new schema immediately.

### Fallback Paths: Because customers rarely follow directions perfectly

Maybe your guide says "send `favoriteSport` at the top level," but the customer ships `fav_sport`, `FavoriteSport`, or `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:favorite_sport`. Instead of going back and forth trying to get on the same page, add **fallback paths** in the dashboard so BYO will look in the other places and still populate `favorite_sport`. Update once, fix it for the entire connection.

![fallback paths in the dashboard](/images/blog/2025-10-02-scim-but-better/fallback.png)

### Fast reads from inside your infra

Sometimes you just want to know what the IdP thinks about a user right now. Maybe you're doing an authorization check for a sensitive operation and need to know the groups the user is in. Maybe you just want to display the user's name in your product. Maybe you need to know if the user is still active.

Because BYO is a **self-hosted sidecar** that runs in _your_ cloud next to _your_ app, calling `getScimUser` to fetch the customer's authoritative view of a user is a low-latency internal hop - not a cross-internet round-trip. You can use this in middleware, on `/whoami` routes, or anywhere you'd consider querying your own user database.

### Know when important data is missing

Some attributes are business-critical (manager email, org role). Mark them **Warn if missing** and the dashboard will flag users that arrived without those values. Your onboarding or support team gets a clear count of warnings and examples to fix.

![warnings in the dashboard](/images/blog/2025-10-02-scim-but-better/warnings.png)

### Built for operators _and_ developers

As with everything in BYO, we designed SCIM support to make life easier for both your engineering team and the folks who will be onboarding and supporting customers. This means it's not just an API, but we also provide:

- **Dashboard for onboarding & support.** See each connection's users/groups, the exact payloads the IdP sent, and your current mappings - then adjust without redeploying.
- **Programmatic everything.** The same normalized properties are returned in SCIM request handling (`parsedUserData`) and via `getScimUser`, so you can enforce policy consistently in code.
- **Fix it yourself, without the back-and-forth.** Update mappings, add fallbacks, and re-check users immediately - no waiting on the customer to reconfigure.

## A quick mental model

1. Your catch-all `/api/scim/*` forwards to BYO.
2. BYO validates and normalizes the request.
3. If an action is required (Link/Disable/Enable/Delete), you perform it in your system, then confirm; otherwise, just return BYO's response.
4. At any time, call `getScimUser` to read the customer-source truth for a user from inside your own infra.

If you already have authentication that works, BYO's SCIM support lets you say "yes" to enterprise asks without rewriting your model or your roadmap. Add the mappings, keep your control, and give customers the provisioning story they expect.


Andrew Israel

SCIM without the pain


Your auth already works... well, mostly.

You've got password login, a users table, and some basic permissions. It's been perfect for your company's needs... until you get **the request**.

There's a deal on the line and the customer needs your auth to change. Sometimes it's simple:

> "We need sessions to expire after 12 hours."

Sometimes it's big:

> "We need SSO with Okta and SCIM provisioning."

And sometimes it shows up as a finding on a security audit:

> "Application must limit the number of concurrent sessions to 4."

Now you have a choice to make.

## The decision: keep building or migrate?

Your first option is striaghtforward: build it yourself. It gives you full control, but it takes time and effort away from your core product.

Your other option is to switch to an external auth provider. This gives you a lot of features quickly, but most external auth providers are designed to be all-in-one solutions. To get the features you need, you have to migrate your users and some of your existing auth code.

We've spent years helping teams through that trade-off when building [PropelAuth Cloud](https://www.propelauth.com). The pattern we kept seeing was the more these customers already had in place, the less appealing a full migration looked.

These companies didn't want to _replace_ their auth - they wanted to **extend** it.

## An auth product that feels like you built it

What we wanted was a solution that gives you the flexibility of something you built yourself while still giving you the speed, future-proofing, and tooling of an external auth provider.

That's why we built **PropelAuth BYO**.

**PropelAuth BYO** is a self-hostable sidecar that **enhances your existing auth** instead of replacing it.
Keep your users table, passwords, and login flows.
Layer on the enterprise features customers ask for - feature by feature, on your schedule - without a migration.

When designing BYO, we focused on a few core principles:

### Self-hosted by design (keep control)

Auth data sprawl creates risk and complexity. BYO runs in _your_ cloud, next to _your_ app, against _your_ Postgres. No fragile webhook chains. No second source of truth. Your data and logging stay in your control.

### Boring to operate (fast to ship)

A sidecar should be uneventful. BYO is a single container with one dependency: **Postgres**. Point at an existing cluster or spin up a dedicated instance.

It's built in Rust, so it's fast under load and frugal with resources. Detailed, structured logs are built in so your SREs aren't flying blind.

### Tooling you'll actually use

Endpoints are necessary; **tooling** is what keeps you sane. BYO comes with:

- A **focused dashboard** for support and security workflows.
- **Structured JSON audit logs** for every action - who, what, when, where, why - ready to ship to your log pipeline.
- Everything you can do in the dashboard, you can also do **via API**, so you can update your internal tools if you don't want to use ours.

### Clean, easy-to-use SDKs

I know, I know, every devtool ever says they are easy to use. Instead of telling you, I'd like to show you one code snippet, annotated with the important design decisions:

```ts
// Each method is a single, focused action, scoped to a single feature.
const result = await auth.sso.completeOidcLogin({
    stateFromCookie: req.cookies["stateFromCookie"],

    // Normally, you'd parse the query params and pass them in
    // But why can't we just do it for you by taking the whole URL?
    callbackPathAndQueryParams: req.url,
});

// Every method returns a Rust-like Result type, so you get explicitly typed
// success and error states to handle.
if (result.ok) {
    // result.data is well-typed and documented
} else if (result.error.type === "LoginBlockedByEmailAllowlist") {
    // Each function has a set of error types that you can handle
    // They are both in the docs and will auto-complete in your IDE
    // Note: We do this differently for each language, to match conventions
}
```

### Add only what you need, when you need it

Each feature is designed to work independently, so you can pick and choose what you want to add.

If you only need better session management, you shouldn't need to adopt a different permissions model to get it.

## When should you actually migrate?

There are still good reasons to replace your auth:

- You're early-stage and don't have a reliable foundation yet.
- You actively dislike your current system and want to hand off operations.
- You need an all-in-one platform with opinionated flows and you're okay adopting its model.

If that's you, migrate. Otherwise, you don't have to.

## For everything else, there's BYO

Keep what works. Add what's missing. Give customers the features they ask for - without moving your users, rewriting your login, or freezing your roadmap.

**Don't migrate your auth. Enhance it.**


PropelAuth Blog

Topics

SCIM without the pain

Don't migrate your auth. Enhance it.

Join the conversation