Inbound SCIM provisioning into authentik: what it does and when to use it
Use an inbound SCIM source when an HR system or another identity provider should be the source of truth for who has an account in authentik and which groups they belong to. Joiners, movers and leavers then flow from the system that already owns that data, and administrators stop creating and disabling accounts by hand in two places. authentik's SCIM source accepts provisioning at a base URL unique to each source, in the form https://<authentik host>/source/scim/<source-slug>/v2, with /v2/Users and /v2/Groups endpoints. Requests are authenticated by a bearer token tied to a service account that authentik creates automatically for the source.
The trade-off is that an external system gains direct write access to your authentication store. A compromised or misconfigured provisioning client can create accounts, add users to groups that unlock applications, or change attributes that policies rely on. The SCIM source token is a high-trust provisioning credential, so treat it like an administrative secret: store it in your secrets manager, restrict which network paths can reach the endpoint, rotate it on a schedule you can state, and confirm which group memberships the service account can influence. Confirm with your HR or IdP vendor exactly which SCIM operations and attributes their connector sends before you go live.
This page walks through configuring the source, the base URL and token handling, and how authentik matches incoming records to existing objects. By default, users are matched by userName and groups by displayName across the whole tenant, so a provisioned record can silently adopt a local account that already exists. Plan for that before the first sync, including how you will find and resolve duplicates. The sections that follow cover correlation, token protection and verification steps.
What you need before configuring the SCIM source
Inbound SCIM provisioning writes users and groups straight into authentik, so the authentik version, the deployment shape, the network path and the token owner all need to be settled before any configuration starts. The cards below cover each prerequisite and the check that confirms it.
Supported authentik release line
Confirm the authentik version you run is on a release line that still receives security fixes. The security policy lists 2026.5.x and 2026.8.x as supported, so an older line should be upgraded before you expose a new high-trust provisioning endpoint. Check the running version in the admin interface and record it in the change ticket, because SCIM behavior can differ between releases.
Server and worker containers
A standard authentik deployment runs a server container, which hosts the core application and an embedded outpost, and a worker container for background tasks. SCIM requests are handled by the server, but the resulting user and group changes depend on the worker processing. Verify both containers are healthy after a test push, and size the worker so a large initial sync does not queue behind other jobs.
PostgreSQL as the system of record
PostgreSQL stores all authentik configuration and data except uploaded files, including the users and groups that SCIM creates and the source configuration itself. Confirm you have a tested backup of the database before the first provisioning run, since a bad sync can create or adopt many objects at once. Use a separately managed PostgreSQL for production rather than a bundled test database.
HTTPS on the authentik host
The sending system must reach the SCIM base URL, which takes the form of your authentik host followed by the source path and version segment. Serve it over HTTPS with a certificate the sender trusts, and confirm the reverse proxy forwards the Authorization header unchanged. Test from the sender's network segment, since a firewall rule that works from your laptop may still block the provisioning host.
Sender SCIM client capabilities
Confirm what the sending system can actually do: which SCIM version it speaks, whether it sends PATCH or only full PUT updates, how it addresses groups and members, and whether it supports bearer token authentication. Ask the vendor to confirm the dialect and endpoint behavior in writing. Some senders assume features such as a discovery endpoint or specific attribute names that authentik must match.
Named owner for the provisioning token
The bearer token is a high-trust credential tied to an automatically created service account, and anyone holding it can create or change users and groups across the tenant. Name one accountable owner in your IAM or platform team before the token is generated, define who may rotate it, and record where it is stored. Plan the rotation procedure in advance so the sender can switch tokens without a provisioning gap.
How to configure the SCIM source step by step
This sequence takes an empty SCIM source to a tested provisioning path from an HR system or upstream identity provider into authentik. Each step ends with a check, so you finish with a working endpoint, a protected bearer token, a verified test user and group, and an audit trail showing that the service account made the changes.
Create the SCIM source and slug
An administrator creates a SCIM source in the authentik admin interface and sets a slug. Pick the slug carefully, because it becomes part of the endpoint the sending system calls. The base URL follows the pattern https://<authentik host>/source/scim/<source-slug>/v2, with /v2/Users and /v2/Groups beneath it. Use your own host and a slug that names the sender, such as hr-example (illustrative), so later logs are easy to read. Done when the source appears in the source list and the base URL shown matches the pattern with your slug.
Retrieve the bearer token
Get the bearer token for the source and store it in your secrets manager, keeping it out of tickets, chat and shared documents. The token authenticates as a service account that authentik creates automatically for this source, so treat it as a high-trust provisioning credential. Confirm in the authentik SCIM source documentation where the token is displayed and how it is rotated. Done when the token sits in the secrets store, access is limited to the people who run the sender, and you can name the service account it belongs to.
Configure the sending system endpoint
In the HR system or upstream identity provider, open the SCIM connector settings and enter the base URL and bearer token from the previous step. Point the connector at the /v2/Users and /v2/Groups endpoints beneath the base URL, and map the sender's attributes to userName, displayName and group membership. Save the configuration and run the sender's own connection test. Done when the sender reports a successful connection test and the token does not appear in the sender's logs or exports.
Check for existing users and groups
Before any test, list the users and groups already in authentik that the sender will touch. By default, authentik matches users by userName and groups by displayName across the whole tenant and adopts the existing objects it finds. A sender that uses a common name can therefore take over a local account or group. Compare the sender's population with authentik's, rename or exclude conflicts in the sender or in authentik, and decide which system owns each name. Done when you have a written list of matches and a named owner for each one.
Create a test user and group
In the sending system, create one clearly labeled test user and one test group. Use identifiers that cannot collide with production names, such as a prefix that marks them as tests. Add the test user to the test group and trigger the sync. Note the time and any request identifiers the sender shows, so you can match them to authentik events later. Done when the sender reports both creates as successful and shows no errors on the membership change.
Verify the user and group objects
In authentik, open the directory and find the test user by its userName and the test group by its displayName. Confirm that the mapped attributes arrived in the expected fields, the user is active, and the test user appears as a member of the test group. Check that the sync did not create duplicate accounts or groups with similar names. Done when the user and group match the sender's record and group membership is the same in both systems.
Verify the service account and audit trail
Locate the service account that authentik created for the source and confirm it is a non-human account with a name that identifies its purpose. Review what the account can reach and confirm that its only activity is provisioning from the sender. Then check the event log for the create actions and confirm they are attributed to that service account. Done when you can show the provisioning actions in the audit trail under the service account and no interactive user performed them.
Remove test objects and record settings
Delete or deactivate the test user and group in the sending system, then confirm how authentik handles that change and whether it matches your lifecycle policy. Confirm this behavior in your own environment before relying on it. Record the source slug, the owner of the sender configuration, the token storage location and the person responsible for rotation in your runbook. Done when the test objects are gone from both systems, the runbook names who can rotate the token, and the source is ready for production scope.
How authentik matches incoming users and groups to existing objects
By default, the authentik SCIM source matches incoming users by userName and incoming groups by displayName, and it searches across the whole tenant, not just the objects created by that source. A matching record is adopted and updated rather than duplicated. This means a feed from an HR system or another IdP can take over an account that an administrator created by hand months earlier, and it can attach that account to a group with the same name as one you already use for access. Treat the first sync as a change to live access, not as a data import. Before you point any system at the endpoint, export the current users and groups from authentik, compare them with the identifiers the feed will send, and confirm that the match behavior is what you intend.
The risks cluster in three places. First, the HR feed may use an identifier that differs from the local account name, such as an employee number, a work email or a formatted display name. Those records will not match, so the sync creates a second user while the original stays active, and the person ends up with two identities. Second, a local break-glass or administrator account may share a username with a new hire or contractor. The matched record is then the privileged account, and the feed's attributes and group memberships are applied to it. Third, group names collide. A group called Finance created for a different purpose can receive every member the feed sends, and because groups often grant application roles, membership changes can widen access in several applications at once. Illustrative example: a contractor named jsmith in the HR feed matches an old admin account jsmith that was never meant for that person.
Before the first sync, build an inventory of every user and group in the tenant, mark which are privileged, and identify which ones the feed should never touch. Then decide, attribute by attribute, which system owns each value, such as name, email, group membership, and whether the account is active. Record that decision in writing so that the person who reviews a later change knows where the authoritative value lives. Confirm with the vendor documentation how the SCIM source handles lookups and whether any identifier other than the defaults can be used in your version. Test the match behavior in a non-production instance with a copy of your data before you connect the production feed.
Mapping SCIM attributes to authentik users and groups
This table compares each core SCIM attribute from the sending system with the authentik user or group field it populates, and notes which side controls the value. Read it as a starting point: the sending system decides what it emits, while authentik decides what it stores locally and what it keeps when the sender stops supplying a value.
| Attribute | Sender controls | authentik field and ownership |
|---|---|---|
| userName | Login identifier emitted by the sender, often the work email or directory login | Matched to an existing authentik user by username across the tenant by default, then adopted; confirm the sender's value is stable |
| displayName or name | Full name as the sender stores it, updated on each sync | Written to the user's name field on create and update; local edits may be overwritten on the next push |
| emails (primary) | Address the sender marks as primary | Written to the user's email field; confirm which address the sender marks primary when several exist |
| active | Whether the sender considers the account enabled | Sets the authentik user's active state; a false value should deactivate access, so test this path before go-live |
| groups (membership) | Group references and member lists the sender sends on the Group resource | Membership is written to authentik groups; authentik-only group memberships may be left in place depending on configuration, so verify |
| Group displayName | Group name as the sender defines it | Matched to an existing authentik group by displayName across the tenant by default, which can adopt a group you did not intend to sync |
| Local-only fields (password, MFA, sessions, local attributes) | Not sent by the sender | Owned by authentik; keep them out of the sender's scope and document any attribute that both sides may write |
Protecting the high-trust SCIM token
The SCIM source token can create, change and adopt accounts across the whole tenant, so it deserves more care than a typical API key. The cards below cover where the token lives, who can touch it, how it is rotated and what the account behind it can reach.
Treat the token as a provisioning credential
The bearer token authenticates the SCIM source, so anyone holding it can create users and groups without signing in as a person. Treat it like an administrator credential rather than an integration detail. Before go-live, confirm in writing which HR or IdP system holds it and who on that side can read it. Note that a leaked token lets an attacker add accounts to groups that carry application access.
Store the token in a secrets manager
Keep the token in a managed secrets store such as OpenBao or your cloud provider's vault, and inject it into the sending system at runtime. Avoid pasting it into tickets, chat, configuration files in version control or shared runbooks. Confirm that secret access is logged, and that the sending system's own admin accounts cannot quietly export the value.
Limit who can view and rotate it
Restrict read and rotation rights to a small named group, separate from people who administer authentik applications. Review that list whenever staff change roles or leave. Where the sending system supports it, require a second approver for token changes so one person cannot both replace the credential and redirect provisioning.
Rotate on staff changes and schedule
Rotate the token when anyone with access leaves, changes role, or when a sending system is retired or re-hosted. Also set a regular rotation schedule chosen by your security policy. Plan the cutover so the sending system stores the new token before the old one is revoked, and confirm in a test source that provisioning still succeeds afterward.
Restrict network paths to the endpoint
The SCIM endpoint sits under your authentik host at the source path. Allow inbound traffic only from the sending system's known egress addresses or from a private network path, and block it elsewhere at the reverse proxy or firewall. Confirm whether your HR or IdP platform sends from fixed addresses, because some SaaS platforms do not publish them.
Review the service account's reach
The token maps to a service account that authentik creates automatically. Open that account and check its group memberships, roles and any permissions it inherits, then remove anything beyond provisioning users and groups. Confirm it cannot change flows, providers or other administrative settings, since a broad service account turns a provisioning leak into a tenant takeover.
Audit provisioning activity
Review authentik's audit trail for events created by the SCIM service account, including new users, group changes and adoption of existing accounts. Because the default matching adopts existing users by userName and groups by displayName, look for unexpected adoptions of administrator or privileged accounts. Forward these logs to your central logging platform and set alerts for bulk changes outside the expected sync window.
Testing provisioning before it touches production users
Run the SCIM source against a staging authentik instance before you point the production sender at it. The goal is to prove that the sender's user and group payloads land where you expect, and that nothing already in production is changed by surprise. Build a test source with its own slug, generate a separate token for it, and keep the staging base URL, https://<authentik host>/source/scim/<source-slug>/v2, distinct from production so that a misconfigured sender cannot write to the wrong tenant. Confirm the exact sender-side settings for your HR system or upstream IdP with that vendor, since the sender controls how it authenticates and which attributes it sends.
Seed the staging tenant with a test population that includes at least one account that already exists locally in authentik, created by hand or by another source, with a userName the sender will also send. Include a group that already exists with the same displayName, because the default behavior matches users by userName and groups by displayName across the whole tenant and adopts what it finds. Before each run, write down the expected result for every test user: adopted, created, or a duplicate. Then compare the outcome against that record. A duplicate account is a failure even if the sync reports success. Also check that adopted accounts keep their existing group memberships and attributes, and confirm the result in the admin interface rather than trusting the sender's log.
Test the lifecycle events the sender will send in production: an account marked inactive, a user removed from a group, a user added to a group, and a user whose attributes change. Record what authentik does for each, including whether an inactive mark prevents sign-in in your flows and whether group removal revokes the access you expect. Finally, write a rollback plan before go-live: identify which objects the test created or adopted, the steps to disable the source and its service account token, and who decides to roll back. Rotate the staging token after testing, and store the production token only in your secrets manager, never in the sender's shared configuration.
Common SCIM provisioning failures and fixes
This table lists the failures teams most often hit when an HR system or another IdP provisions into authentik through the SCIM source, with the likely cause, the check to run and the fix for each. Use it as a first-pass triage list, then confirm the exact error text and log entries for your authentik version before changing anything.
| Failure | Likely cause and check | Fix |
|---|---|---|
| 401 responses from the SCIM endpoint | The bearer token is wrong, was rotated in authentik but not in the sending system, or was copied with extra whitespace. Check the token value against the service account the source created, and confirm the request header format in the authentik logs for your version. | Reissue or copy the token from the SCIM source, update the sending system's secret store, and send a test request to the /v2/Users endpoint before re-enabling sync. |
| Base URL unreachable | The sending system cannot reach https://<authentik host>/source/scim/<source-slug>/v2 because of a reverse proxy rule, a DNS name that resolves to the wrong place, a certificate the sender does not trust, or a path that drops the source prefix. Test from the sender's network, not from your workstation. | Fix the proxy route so the source path reaches the authentik server, correct DNS or certificate chain, and confirm the slug in the URL matches the source exactly. |
| Duplicate accounts from mismatched userName values | The sender uses a different identifier format for userName than existing authentik users, such as an email address in one place and a short login in another. Because users are matched by userName across the tenant, the sender may create a second account instead of updating the first. Compare a sample of records from both systems. | Agree on one userName format with the HR or IdP owner, normalize existing usernames in authentik, and merge or deactivate duplicates after confirming which account holds the application history. |
| Group membership not updating after a rename | Groups are matched by displayName across the tenant. If the sender renames a group, authentik may treat it as a new group or fail to find the old one, so membership changes appear to stop. Check whether a group with the old or new name exists and which one holds the members. | Keep displayName stable in the sender, or rename the group in one controlled step in both systems. Verify membership on a test user after the change and remove any orphaned duplicate group. |
| Unexpected adoption of existing local accounts | A SCIM record matches a local user or group that an administrator created by hand, so authentik attaches the provisioned data to an account that was never meant to be managed by the sender. Review which local accounts share a userName or displayName with the sender's records before the first full sync. | Inventory existing users and groups before enabling the source, rename or exclude local accounts that should stay outside SCIM, and run the first sync against a limited test population. |
| Deprovisioned users still able to sign in | The sender sends a deactivation or delete, but the update is not processed, or the user was adopted from a local account and still has a usable password or other sign-in path. Check the user's active state and the sender's job history for failed requests. | Confirm the sender's deprovisioning events reach authentik, disable local password and other sign-in methods for adopted accounts where policy requires, and review active sessions after a removal. |
| Sync errors on a subset of records | Individual records may fail on required attributes, unexpected characters or group references to members not yet created. Compare the failing payloads with the attribute mapping and the order in which users and groups are sent. | Correct the source data or mapping, send groups and users in an order that resolves references, and re-run the failed records after the fix. |
| Token exposure or unexpected reuse | The high-trust token appears in a ticket, log, script repository or shared password vault that more people can read than should have access. Anyone holding it can create and change users and groups. | Revoke and reissue the token, move it into a restricted secret store, limit who can view the source, and review audit records for changes made during the exposure window. |
Questions buyers ask about SCIM provisioning into authentik
Is the SCIM source included in the open-source edition of authentik?
The authentik repository puts most of its code under the MIT license, and the SCIM source is part of that core code base, so you do not need to buy a paid tier to use it. The split matters for the enterprise directory features. The enterprise license covers code in the authentik/enterprise/ directory, and the pricing page lists Google Workspace and Microsoft Entra ID integrations as enterprise-only. Before you rely on any of this, confirm the current feature placement with authentik, because a SCIM feed from an Entra ID or Google Workspace tenant may pull in enterprise-only integrations on the other side. Check the authentik LICENSE file and the pricing page together before you commit to a design.
What makes SCIM provisioning into authentik take more or less effort?
Effort rises with the number of user attributes you map, how your group model is built, and how well identifiers line up across systems. The main drivers are:
- The number of attributes that must land in authentik user properties, and how many need transformation before they are usable.
- Whether your group model is flat or nested, and whether group names are unique across the tenant.
- Whether the sending system uses the same
userNameanddisplayNamevalues that authentik matches on by default. - Quirks in the sender, such as non-standard payloads, PATCH behavior, or how it deletes or deactivates users.
Each of these adds testing time, so ask for them to be listed in the written scope.
How long does it take to scope SCIM provisioning into authentik?
Scoping is the stage where the attribute list, group model and matching rules get agreed, and its length depends on how many systems and owners are involved and how clean the source data is. No duration is fixed for this page, so ask for one in writing with the scope. A good scoping output names the sender, the attributes, the correlation rules, the group structure, the test users and the cutover plan. If your HR or IdP owner cannot yet describe those items, expect the scoping phase to take longer.
What does the work need from our HR or IdP owner and our security team?
The HR or identity owner needs to explain the source of truth for each attribute, confirm the lifecycle events (joiner, mover, leaver), and agree on which group names are authoritative. The security team needs to approve the handling of the bearer token, decide where it is stored, and review who can rotate it. Both teams should agree in writing on what happens when a user is removed upstream, since that decision affects access and audit trails. Plan for these reviews early, because they often decide the timeline more than the technical build does.
Can our own team set up SCIM provisioning into authentik without outside help?
Yes, a team with solid familiarity with authentik, its source model and the sending system can build it internally. The questions to answer honestly are whether someone owns the matching rules, whether the sender's SCIM behavior is documented or known, and whether there is capacity to test edge cases like deactivations and group membership changes. Many teams do the build but want an outside review of the token handling and correlation design before going live. DeployOpen plans, implements and hardens these integrations in your own infrastructure under a written, fixed scope, so you can compare that option with building internally.
What is the main security risk with an inbound SCIM token?
The SCIM source token is a high-trust provisioning credential, so anyone holding it can create or change users and groups. By default, authentik matches users by userName and groups by displayName across the whole tenant and adopts existing objects, which means a token or a sender mistake can take over accounts that were created elsewhere. Limit who can read the token, store it in a secrets manager, rotate it on a schedule you define, and test correlation with a copy of production data before you connect a live HR feed.
Which pricing items should we confirm on the authentik pricing page?
Confirm which edition includes the functions you plan to use, since the pricing page lists three editions: Open Source, Enterprise and Enterprise Plus. Check the Enterprise per-user and per-external-user charges, the minimum for Enterprise Plus, and whether support tiers, ticket-based support thresholds or FIPS compliance affect your choice. Ask authentik to confirm how these charges apply to users created by SCIM provisioning, because user counts are the basis for the Enterprise pricing. Also confirm which upstream integrations you need are covered by your chosen edition. Review the authentik pricing page before your scope discussion.
How DeployOpen scopes and delivers SCIM provisioning for authentik
DeployOpen plans, builds, documents and supports the inbound SCIM source in authentik inside your own infrastructure, starting from a written scope. The work centers on who may create and change users and groups, how incoming objects match existing ones, and how the high-trust token is stored and rotated.
How we scope
- Engagements are fixed-scope, with the provisioning source, upstream system and object types agreed in writing before work starts.
- The written scope records which attributes flow in, which groups are mapped, and how existing users and groups will be correlated.
- Scope also records the token storage location, rotation owner and the environments covered, such as test and production authentik instances.
How we build
- We configure the SCIM source endpoint, service account and token, and confirm the base URL resolves from the upstream provisioner.
- We test correlation by userName and displayName against a copy of your current directory before any live provisioning is enabled.
- We set property mappings and group handling so incoming changes match the behavior your access model expects, and we verify them end to end.
How we hand over
- You receive documentation of the source configuration, mappings, correlation rules and the token custody and rotation procedure.
- We provide a verification checklist covering create, update and deactivate events for users and groups, with results recorded for your team.
- Runbooks describe how to revoke the token, pause the source and recover from a bad sync, so your operators can act without us.
How we support
- Ongoing support, upgrades and testing after handover are available as a retainer, scoped separately from the original project.
- Retainers can cover reviews of authentik release notes that affect the SCIM source before you upgrade your authentik deployment.
- Confirm with us in the quote which support hours, response expectations and upgrade work are included, since these vary by scope.
