
AWS Cognito is one of those services that feels like it can do almost anything if you're willing to wrestle with it long enough. User pools, app clients, hosted UIs, custom auth flows, Lambda triggers... it's an incredibly configurable authentication service, but that flexibility often means you have to build a lot of the features you want on top of it.

While you might be used to working around Cognito's quirks, one significant limitation stands out: AWS Cognito doesn't support **SCIM**.

If you aren't familiar, SCIM is a protocol designed to make it easier for your customers to manage user identities in your application. Your customers can use SCIM to automatically provision, deprovision, and update user accounts in your app based on changes in their own identity providers (like Okta, Entra, or JumpCloud). [Here's](/post/scim-but-better) a guide on what SCIM is and why it matters.

In this post, we'll look at how you can add SCIM support to Cognito without forcing you to rip out or migrate your existing authentication, using [PropelAuth BYO](https://byo.propelauth.com).

## Handling SCIM Requests

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 Identity Providers (IdPs) behave differently.

In order to support SCIM, you'll need to implement all these endpoints. To make it easier, with PropelAuth BYO you stand up a single catch-all route (e.g. `/api/scim/*`) and [forward requests to the sidecar](https://docs.byo.propelauth.com/scim/reference#scim-request). We parse the incoming SCIM requests and reduce them down to a few simple handler functions that you can implement.

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

Then, all you need to do is handle the different responses that BYO returns and you'll have a fully functioning SCIM implementation. Let's look at the different types of resopnses BYO will return and how to handle them.

### No action required

The most common case is when no action is required from your application. Some examples of when this might happen are:

- SCIM is asking for a list of users they already provisioned to see who else they should provision
- SCIM is querying your app for supported schemas or resource types
- SCIM is fetching a user so they can see if they need to update anything
- SCIM is updating a user, but they didn't actually change anything (not all IdPs are perfect)

In all of these cases, you don't need to take any action, but you do need to provide a valid response back to the IdP. BYO will provide you with an HTTP status code and a formatted response body that you can pass back to the IdP. For TypeScript, as an example, it might look like this:

```ts
if (result.ok && result.data.status === "Completed") {
    // Respond to SCIM IdP with the response data
    res.status(result.data.responseHttpCode).json(result.data.responseData);
}
```

### Disable User

When a user is deprovisioned in the IdP, BYO will return a status of `ActionRequired` and an action of `DisableUser`. Importantly, this is NOT a delete action and can possibly be
reversed later if the user is re-provisioned.

You should call [AdminDisableUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDisableUser.html) for this user which will prevent them from logging in and will invalidate any existing tokens. Afterwards, you should [confirm with BYO](https://docs.byo.propelauth.com/scim/reference#commit-scim-user-change) that you performed the action, and BYO will provide you with the HTTP status code and response to send back to the IdP.

### Enable User

The opposite of disabling a user, when a user is re-provisioned in the IdP, BYO will return a status of `ActionRequired` and an action of `EnableUser`.

You should call [AdminEnableUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminEnableUser.html) which will allow the user to log in again. Afterwards, you should [confirm with BYO](https://docs.byo.propelauth.com/scim/reference#commit-scim-user-change) that you performed the action, and BYO will provide you with the HTTP status code and response to send back to the IdP.

### Delete User

In some cases, an IdP will expect a user to be fully deleted from your system. This can be done because an employee has left the company or after a configurable amount of time passes since the user was disabled.

No matter the reason, when BYO returns a status of `ActionRequired` and an action of `DeleteUser`, you should call the [AdminDeleteUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDeleteUser.html) function. Afterwards, you should [confirm with BYO](https://docs.byo.propelauth.com/scim/reference#commit-scim-user-change) that you performed the action, and BYO will provide you with the HTTP status code and response to send back to the IdP.

### Link User (a.k.a Create/Provision User)

The final case is creating or provisioning a new user. This will depend a bit on your existing Cognito setup.

If you create a new user pool for each customer, you can use [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html) to create the user in the appropriate user pool (which can be determined using the `customerId` provided by BYO). You'll then need to call [the link function in BYO](https://docs.byo.propelauth.com/scim/reference#link-scim-user) which will register this user's ID with BYO so future SCIM requests will use your IDs for users.

If you have a shared user pool, you'll still use [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html), but you may need to handle the case where the user already exists (for example, if they had an account before they set up SCIM provisioning). In that case, you can either skip creating the user (and instead just link them) or throw an error to allow you to handle it however you see fit.

## Managing SCIM Connections

Now that you've implemented the SCIM handlers, the only thing left to do is manage your SCIM connections for each customer. With PropelAuth BYO, you can use the BYO Dashboard to create and manage SCIM connections for each of your customers or you can do it all [programmatically](https://docs.byo.propelauth.com/scim/management-reference).

Whichever you use, your customer just needs to know the SCIM Base URL (the location of your wildcard SCIM endpoint, we used `https://example.com/api/scim` earlier) and a SCIM API Key (which will be generated in the dashboard or programmatically).

We provide [detailed guides](https://docs.byo.propelauth.com/scim/example-setup-guides/overview) for setting up SCIM with popular IdPs and we also provide frontend components that you can drop into your application to allow your customers to self-serve their SCIM configuration.

## 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.

For a deeper dive into how BYO's SCIM support works, check out our [blog post on SCIM](https://byo.propelauth.com/post/scim-but-better) or our [documentation](https://docs.byo.propelauth.com/scim/overview).

If you have any questions or need any help getting started, feel free to reach out to us at [support@propelauth.com](mailto:support@propelauth.com).


Andrew Israel

Implementing SCIM with AWS Cognito


You've already implemented Enterprise SSO. Your customers can log in with Okta, Entra, or their Identity Provider (IdP) of choice. But now they're asking:

- "When someone leaves, their access needs to be revoked immediately"
- "Can you automatically provision users when they're added to our IdP?"
- "We need user groups synced from Entra"

What they're asking for is **SCIM (System for Cross-domain Identity Management)** - automated user provisioning and deprovisioning that ensures their employee directory stays perfectly in sync with your application.

## What is SCIM and why do you need it?

Enterprise SSO only handles the login process. It doesn't tell you when someone joins the company, changes departments, or leaves the company. Without SCIM, you won't know a user should be deactivated until they try (and fail) to log in next time.

**SCIM automatically syncs user information between your customer's IdP and your application.** When someone joins your customer's company and gets added to Okta, they're automatically created in your product. When they leave and IT disables their account, they're immediately locked out of your product too.

The value proposition is clear: your customers' IT teams manage users in one place (their IdP), and those changes automatically propagate to all their SaaS tools, including yours.

## How does SCIM work?

Conceptually, SCIM is actually pretty simple. Your customer's IdP (Okta, Entra, etc.) will make API calls to your application to keep users in sync. These API calls do things like:

- Fetch the current list of provisioned users
- Create new users
- Update user information when it changes
- Deactivate or delete users when they're removed

The challenge isn't the concept, it's the implementation. SCIM has a very specific format for these API requests and responses. The specification itself is detailed but also somewhat vague, and each IdP tends to implement it slightly differently. Some use PUT requests with the full user object, others use PATCH with only changed fields. Sometimes those patches provide a field and a value, other times they provide a JSON object and no path, but instructions like replace or remove.

Let's break down the key parts of adding SCIM support to your product.

## Adding SCIM Support to your product

There are two main parts to adding SCIM support:

1. Providing an API key or token for authentication
2. Setting up the SCIM endpoints to handle provisioning requests

### Providing a SCIM API key

The SCIM endpoints you're about to create are sensitive - they can create, update, and delete users in your application. You need to ensure only authorized requests from your customer's IdP can access them.

The standard approach is to [provide your customer with an API key](https://docs.byo.propelauth.com/scim/management-reference#create-scim-connection), which they enter into their IdP's SCIM configuration. This key is then included in the `Authorization` header of each request to your SCIM endpoint.

Here's where your customers would enter the API key in Okta:

![okta scim api key setup](/images/blog/2025-10-27-adding-enterprise-sso-scim/okta-scim-api-key-setup.png)

With PropelAuth BYO, we handle all the API key generation, storage, and validation for you. If you build it yourself, make sure to securely store the keys and validate them on each request.

### Setting up the SCIM endpoints

Your customers will also need a "SCIM Base URL" - the root URL where your SCIM endpoints live. For example: `https://api.yourapp.com/scim/v2/`. The IdP will make requests to endpoints like:

- `GET /scim/v2/Users` - List users
- `POST /scim/v2/Users` - Create a new user
- `GET /scim/v2/Users/{id}` - Get a specific user
- `PUT /scim/v2/Users/{id}` - Replace a user's information
- `PATCH /scim/v2/Users/{id}` - Update specific fields of a user
- `DELETE /scim/v2/Users/{id}` - Delete a user
- Similar endpoints for `/Groups` if you support group syncing

You can see the full specification in the [SCIM 2.0 standard](https://datatracker.ietf.org/doc/html/rfc7643) and [SCIM Protocol](https://datatracker.ietf.org/doc/html/rfc7644). One thing to note is that most IdPs don't implement the full spec. Filters, for example, can technically be complex and invliolve multiple attributes and logical operators, but in practice, most IdPs only use simple equality checks on a single attribute (like `userName eq "example@acme.com"`).

If you use PropelAuth BYO, you can [forward any SCIM request](https://docs.byo.propelauth.com/scim/reference#scim-request) to us, and we'll return the exact response to send back to the IdP, plus any critical actions you need to take in your system. Our goal is to standardizes the SCIM implementation across all IdPs as best we can.

## Matching SCIM users to SSO users

Here's where things get tricky. You already have users logging in via SSO, and now SCIM is creating/updating/deleting users. How do you match them up?

You'd think SSO and SCIM would use the same unique identifiers, but that's often not the case. Different IdPs use different default configurations, and everything is customizable.

There are two common approaches for handling this:

**Match on email address:** Simple, works across all IdPs, and easy to understand. However, email addresses can change, which can cause matching issues.

**Configure the externalId to match the SSO ID:** SCIM's `externalId` field is an optional field that's meant to be an immutable unique identifier. You can provide instructions to your customers on configuring this to match their SSO subject claim. More robust than email matching, but requires customer configuration.

As auth people, we generally recommend using the `externalId` approach, but there are a lot of products that do the first one and just add a warning about email changes.

With PropelAuth BYO, we provide a UI that lets you see the full user object coming from SCIM to help you debug possible matching issues.

![byo scim user object](/images/blog/2025-11-04-adding-scim/byo-scim-user-object.png)

## Decisions to make when implementing SCIM

### Just-in-time provisioning vs pre-provisioning

When you set up SSO _without SCIM_, users are typically created "just-in-time" (JIT), meaning that you create the user when they log in for the first time.

One of the key points of SCIM, however, is to allow your customers to provision users before they log in. And this raises an important question: what happens when a user logs in but is NOT provisioned via SCIM?

This may seem like a weird edge case, but it happens somewhat commonly. Here's a few examples that come up a lot:

- Azure / Entra SCIM syncs are not immediate. You'll often see a 30-40 minute delay between when a user is given access to your product in Entra and when SCIM sends you a provision request. If that user tries to log in during that window, they'll be allowed to login (as they do have access), but you won't have a SCIM record for them yet.
- If you are using Okta for OIDC and SCIM, you need to have two separate applications in Okta (SAML and SCIM doesn't have this issue, but that's a whole separate discussion). If your customer gives a user access via the SSO application but not the SCIM application, that user will be able to log in, but won't be provisioned via SCIM.

How you handle this is up to you. Some products will choose to reject logins for users that aren't provisioned via SCIM (the argument being "all provisioning is now SCIM provisioning"). Others will allow JIT provisioning to continue working alongside SCIM provisioning (the argument being "if the user can log in, they should be able to").

For my personal take, it's pretty reasonable to allow JIT provisioning to continue working, if for no other reason than it avoids the "I gave my employee access in Entra but they still can't log in" support tickets.

### Supporting custom properties / attributes

If I have any specific grievances with the SCIM spec, it's that they didn't do a great job of explaining how to handle custom attributes. There are a core set of attributes (email, name, active, etc.) and even extensions for enterprise-specific attributes, but many products need to support custom attributes specific to their domain.

The good news here is that every IdP does have support for custom attributes, the real question is just where your users should put them.

There are two main approaches here:

**Send the custom attributes as top level fields**: Want to collect a `favoriteSport` attribute? Just have your customer map that attribute in their IdP to a top-level `favoriteSport` field in SCIM. It's a pretty straightforward approach, but it does clutter up the top-level namespace. We've also seen a cases where customers have built their own SCIM clients that don't expect custom fields, leading to errors.

**Send the custom attributes in an extension schema**: SCIM supports the concept of extension schemas, which are basically custom namespaces for additional attributes. You can define your own schema (e.g. `urn:ietf:params:scim:schemas:extension:YOUR_PRODUCTS_NAME_HERE:2.0:User`) and have your customers map their custom attributes into that schema. This keeps things more organized, but requires a bit more setup on both sides.

The best approach is to define your own extension, meaning customers will send custom attributes like this:

```json
{
    //...
    "urn:ietf:params:scim:schemas:extension:YOUR_PRODUCTS_NAME_HERE:2.0:User": {
        "favoriteSport": "soccer"
    }
}
```

Some customers will still accidentally send them as top-level fields, so be prepared to handle both cases if you want to be flexible.

For PropelAuth BYO, we have a detailed guide on [handling custom attributes via SCIM](https://docs.byo.propelauth.com/scim/custom-properties), which also covers features like `fallbackPaths` (allowing you to specify multiple possible paths for an attribute) and `Warn if missing` which can warn you if a customer isn't sending an important attribute.

![scim ui custom attributes](/images/blog/2025-11-04-adding-scim/byo-scim-custom-attributes.png)

## Delete vs Deactivate

We've covered most of the complexities of SCIM, but one final thing to call out is that deletion and deactivation are not the same thing.

Deactivating a user (literally, setting the `active` field to `false`), means the user still exists in your system, but can't log in. This is a reversible operation. Later on, users can be reactivated and ideally retain all of their data and settings.

Deleting a user, on the other hand, is a permanent operation. The user is removed from your system entirely, and all of their data is typically deleted as well.

Entra / Azure, for example, will initially just deactivate users via SCIM. After a grace period, they will then send a delete request. This is handy to avoid accidental data loss, but it's just something to keep in mind in case a customer writes in about it.

## PropelAuth BYO makes adding SCIM simple

PropelAuth BYO is a self-hostable authentication sidecar that makes adding SCIM to your product easy. You keep your existing auth system and we handle the SCIM complexity for you.

All you have to do is set up a single catch-all route (e.g. `/scim/v2/*`) and forward all SCIM requests to the PropelAuth BYO sidecar. We'll return to you the exact response to return back to the IdP, plus any critical actions you need to take in your system (like creating or deleting users).

You also get:

- Pre-built SCIM endpoints that work with all major IdPs
- Automatic handling of IdP-specific quirks
- API key management
- Detailed logs of all SCIM operations

Check out [PropelAuth BYO](https://byo.propelauth.com) to add SCIM without the complexity.


Adding SCIM to your product


Your enterprise customers are asking:

- "Can we use Okta to log in?"
- "We need automatic user provisioning from our IdP"
- "When someone leaves, their access needs to be revoked immediately"
- "Can we sync user groups from Entra?"

What they are actually asking for is **Enterprise SSO (Single Sign-On)** and **SCIM (System for Cross-domain Identity Management)**.

In this post, we'll cover what Enterprise SSO and SCIM are, what decisions you need to make when adding them to your product, and how to implement them at a high level. Along the way, we'll also link to documentation showing you how to add Enterprise SSO and SCIM using [PropelAuth BYO](https://byo.propelauth.com), our self-hosted authentication sidecar.

## ELI5: SSO and SCIM

**SSO (Single Sign-On)** is how users log in. It's an alternative to logging in to your product with an email and password.

Enterprise SSO lets your customers' employees log into your app using their existing company credentials. They enter some information about themselves (this is often their email address) and are redirected to their company's login portal (this is often a tool like Okta, Entra, JumpCloud, etc). The value that the customer gets is they set this up for ALL the products they use (like GitHub, Slack, and your product), meaning their employees have one shared account for everything they need to get their job done.

![example SSO flow](/images/blog/2025-10-27-adding-enterprise-sso-scim/sso-flow.gif)

Enterprise SSO only handles the login process, though. And this leads to a few important questions like, "What happens if a user's email address changes?" or "What if they leave the company?" Well, you wouldn't really know until they next try to log in, which can be a problem for some applications. This is where SCIM comes in.

**SCIM (System for Cross-domain Identity Management)** automatically syncs users' information to your application. When someone joins your customer's company and gets added to Okta, they're automatically created in your product. When they leave and IT disables their account, they're immediately locked out of your product too.

The value of SCIM is that it automates user management. Your customers don't have to manually add or remove users from all the products they use - their identity provider (Okta, Entra, etc.) does it for them.

## Adding SSO and SCIM to your product

Enterprise SSO and SCIM are table stakes for any product selling to mid-market or larger companies. But they can be complex to implement, especially if you're not familiar with identity protocols.

The good news: with PropelAuth BYO, you can add both without migrating to an external auth provider, giving up your user data to a third party, or rewriting your auth system.

But before we get into the implementation details, we have to make an important architectural decision.

## The account merging question

What happens when an **existing user** wants to log in with SSO?

Let's say `jane@acme.com` already has an account in your product with a password. Acme Corp just set up Enterprise SSO. When Jane tries to log in with her Identity Provider (IdP), what should happen?

### Option 1: Convert the existing account to an SSO account

The current account for `jane@acme.com` merges with the SSO login.
Jane can no longer log in with a password - she must use SSO.

The good news is she keeps all her data, settings, history - and possibly most importantly, her user ID.

While this might seem rare, it's actually quite common. Customers will try out your product with a few users first, and then later decide to roll it out more broadly with SSO. If you don't merge accounts, those initial users will lose all their work. And those initial users are often your champions at the company.

However, whenever you merge accounts, you need to be cautious. The safest route here is to email Jane a confirmation link before converting her account. This way, you ensure that the person logging in with SSO is indeed the owner of the existing account.

**Pros:**

- Seamless user experience
- No data migration needed
- Users don't lose their work

**Cons:**

- Need to handle account merging carefully

### Option 2: Keep Enterprise SSO accounts separate

Treat SSO logins as completely separate accounts. If `jane@acme.com` logs in with SSO, she gets a brand new account, even if she already had one with a password.

**Pros:**

- Simpler implementation
- Clear security boundaries
- No ambiguity about account ownership

**Cons:**

- Users might lose access to existing data
- Potential confusion with multiple accounts
- Migration path needed for existing users

### Which should you choose?

Both options are reasonable. If you keep your customers / tenants isolated already, option 2 is a no-brainer.

We often recommend option 1, since you get a better user experience for users switching to SSO. You just need to be careful to never merge accounts without an email confirmation step. You can always err on the side of security, return an error, and ask the user to contact support if you're unsure.

## Adding SSO Support

With that out of the way, there are three main parts to adding SSO support:

1. Allowing customers to configure SSO settings in your product.
2. Updating your login flow to support SSO.
3. Handling the SSO callback and creating user sessions.

### Allowing customers to configure SSO settings

When a customer wants to set up SSO, you and them need to exchange some information. For OIDC-based SSO (the more modern option), your customer will need to provide information like:

- `client_id` - The identifier for your application in their IdP.
- `client_secret` - A secret key used to authenticate your application with their IdP.
- `authorization_endpoint` - The URL where users are redirected to log in.
- `token_endpoint` - The URL where your application exchanges authorization codes for tokens.
- `userinfo_endpoint` - The URL where your application can retrieve user information.

Each IdP is a bit different, but you can refer to [our documentation](https://docs.byo.propelauth.com/sso/example-setup-guides/overview) for example setup guides for popular IdPs like Okta, Entra, Google Workspace, OneLogin, and JumpCloud.

You will also need to provide your customer with a `redirect_uri` - this is the URL in your application where the IdP will send users after they log in. This URL typically looks something like `https://yourapp.com/auth/callback`.

With PropelAuth BYO, you can manage this configuration manually via the dashboard or [programmatically via the API](https://docs.byo.propelauth.com/sso/management-reference#create-oidc-client). For other libraries/services, you'll want to consult their documentation on how to store and manage OIDC client configurations.

### Updating your login flow to support SSO

Once the SSO connection is configured, you'll need to update your login flow to support it. The main question to answer is "How can I redirect enterprise customers to a login page just for them, while still supporting regular email/password logins for other users?"

There are generally two approaches people take here:

**SSO-first login flow:** On your login page, you ask users to enter their company email address first. You then check if that **email's domain** is associated with an SSO configuration. If it is, you [redirect them to the IdP's login page](https://docs.byo.propelauth.com/sso/reference#initiate-oidc-login). If not, you show the regular email/password login form.

![example sso first login flow](/images/blog/2025-10-27-adding-enterprise-sso-scim/sso_first_login.gif)

**Keep SSO separate:** You have a separate button for Enterprise SSO logins. Users who want to log in with Enterprise SSO click that button and are taken to a page where they enter their company information to initiate the SSO flow.

Which you should choose depends on your user base. If most of your users are from enterprises, the SSO-first approach makes sense. If you have a mix of enterprise and individual users, keeping SSO separate is often clearer.

### Handling the SSO callback and creating user sessions

No matter which login flow you choose, the overall flow is the same:

- The user is redirected to the IdP's login page (in other words, they are redirected to their employer's login page)
- The user logs in with their company credentials
- The IdP redirects the user back to your application's `redirect_uri` (e.g. https://app.example.com/auth/callback) with an authorization code
- (You are here) Your application exchanges that authorization code for the user's information and creates a session for them

You can think of this callback as "finishing" the login process. Once you [handle the callback](https://docs.byo.propelauth.com/sso/reference#complete-oidc-login), you'll receive the user's information, such as their email address, name, and any other claims the IdP provides.

From here, you can upsert the user into your database (creating a new user if they don't exist, or updating their information if they do) and create a session for them (just like you would for a regular login).

And that's it! Each of your customers only need to set up the SSO connection once, and after that, all of their employees can log in using their company's credentials.

## Adding SCIM Support

SCIM, in theory, is pretty straightforward. Your customers' IdP has all the information about their users, and they just need to send that information to your application. This leads to two main tasks:

1. Providing an API key or token for your customer to authenticate with your SCIM endpoint.
2. Setting up the SCIM endpoints to handle user/group provisioning requests.

### Providing a SCIM API key or token

The endpoints that we are going to set up are pretty sensitive. They can create, update, and delete users in your application. We want to make sure that only authorized requests from your customer's IdP can access them.

The common approach here is to [provide your customer with an API key](https://docs.byo.propelauth.com/scim/management-reference#create-scim-connection), which they enter into their IdP's SCIM configuration. This key is then included in the `Authorization` header of each request to your SCIM endpoint.

If you'd like to see what this looks like, we have [guides for popular IdPs](https://docs.byo.propelauth.com/scim/example-setup-guides/overview), and here's where your customers would enter the API key in Okta:

![okta scim api key setup](/images/blog/2025-10-27-adding-enterprise-sso-scim/okta-scim-api-key-setup.png)

### Setting up the SCIM endpoints

You'll also notice in that screenshot that Okta asks for a "SCIM Base URL". This is the URL where your SCIM endpoints will live. For example, you can use `https://api.yourapp.com/scim/v2/` and the IdP will make requests to endpoints like `https://api.yourapp.com/scim/v2/Users` and `https://api.yourapp.com/scim/v2/Groups`.

We won't go into the full details of implementing a SCIM server here, but each IdP will use your SCIM endpoints to perform actions like:

- Getting a list of users
- Provisioning a new user
- Updating an existing user (some IdPs will use PUT and give you the full user object, others will use PATCH and only give you the fields that changed)
- Deactivating or deleting a user

The most important thing to make sure of, is that when you get a critical action like deactivating a user, you immediately revoke their access to your application. This is the main value of SCIM - ensuring that when someone leaves the company, they can no longer access your product.

If you use PropelAuth BYO, you can just [forward any SCIM request (including the path and method)](https://docs.byo.propelauth.com/scim/reference#scim-request), and we'll return the exact response to return to the IdP as well as any critical actions you need to take. Our goal is to standardize the SCIM implementation so you don't have to worry about the various quirks of each IdP.

## Gotchas and common questions

Once you have SSO and SCIM set up, there are a few common questions and gotchas that come up.

### How do I match SCIM users to SSO users?

Matching users between SSO and SCIM is important for all those SCIM operations to work correctly. For example, when a user is deactivated via SCIM, you need to make sure that the correct user is deactivated in your system.

You'd imagine this would be straightforward and they both have the same unique identifiers, right? Unfortunately, no. All IdPs are different, and it's fairly common for the default settings to provide IDs that do not line up. This is made somewhat worse by the fact that IdPs also make everything configurable.

This is again a case where there are two common approaches:

**Match on email address:** This is a simple approach, works around the quirks of different IdPs, and is easy to understand. That being said, email addresses can change, so it's not always ideal to use it as the unique identifier.

**Provide instructions to customers to configure the externalId to match the SSO ID:** SCIM has a few fields that can be used as identifiers like `userName` and `externalId`. `externalId` is meant to be an immutable unique identifier for the user, making it a great choice for matching users between SSO and SCIM. You can provide instructions to your customers on how to set up the externalId properly which is more robust than matching on email, but... well, people don't always follow instructions.

With PropelAuth BYO, we have a UI that let's you test and configure how users are matched between SSO and SCIM. You choose which field to match on for both SSO and SCIM, and we show you which users would NOT be matched based on your configuration.

![propelauth scim sso matching](/images/blog/2025-10-27-adding-enterprise-sso-scim/propelauth-scim-sso-matching.png)

### Are there any cases where I want to allow both SSO and password logins?

Once Enterprise SSO is set up, most customers will want to enforce all their employees are required to login with it. In practice, however, there are a few exceptions:

- Contractor access. Not all contractors will be in the company's IdP, so they may need to be special cased to allow password logins.
- Your support/success teams access. You may want to create accounts in your customer's tenant for your internal teams to help them troubleshoot issues. Customers won't often onboard your team members into their IdP, so password logins may be necessary here as well.
- Backup access. Some customers may want to have a few "break glass" accounts that can log in with a password in case their IdP is down.

### Email address validation

One thing to be aware of is that most IdPs **do not** validate email addresses. If you do any kind of account merging based on email addresses, you need to be cautious.

One common constraint is to only allow Enterprise SSO logins from a set of verified email domains. This way, if someone tries to log in with SSO using an email address that doesn't belong to the company, you can block it.

## PropelAuth BYO makes adding Enterprise SSO and SCIM easy

As you can see, there are a lot of moving parts when it comes to adding Enterprise SSO and SCIM support... and that doesn't even include keeping up to date with the various requirements of the different IdPs. Instead of burning tons of engineering cycles to get your Enterprise customers the login methods they need, use PropelAuth BYO to get up and running in an afternoon.


Adding Enterprise SSO & SCIM to any product


# 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.


Scim Posts

Topics

Implementing SCIM with AWS Cognito

Adding SCIM to your product

Adding Enterprise SSO & SCIM to any product

SCIM without the pain

Join the conversation