Langfuse Okta SSO and SCIM provisioning

Okta does not support SCIM on a custom OIDC app, so Langfuse's Okta guide calls for two Okta applications. The first is an OIDC app that handles sign-in to Langfuse. The second is a separate SCIM app that handles user provisioning into the Langfuse organization. Teams that expect one application to cover both jobs will find that the provisioning side has no place to attach. The split also means a person can be able to sign in while holding no Langfuse role, because authentication and membership are managed by different objects. Plan for both apps before SSO is declared working.

The two apps share one population of users but carry different responsibilities. The OIDC app decides who can authenticate and passes them into Langfuse through the SSO configuration. The SCIM app calls Langfuse's SCIM endpoints, which sit under the public API path and authenticate with an organization-scoped API key, to create memberships and remove them. SCIM does not set passwords, so every sign-in still runs through the OIDC app. Each app therefore needs its own assignments: the OIDC app assigned to users who should sign in, and the SCIM app assigned to users who should hold organization membership. Confirm in writing which group or user set feeds each app.

Before changing any assignment, name both apps and document them together. The record should state each app's purpose, the users and groups it covers, the Langfuse organization it targets, the owner of the API key used for SCIM, and the roles attribute the SCIM app will send. That last item matters because Langfuse defaults the role to NONE when no roles attribute is provided, and deprovisioning and reprovisioning can overwrite an existing organization role with that attribute. Assignments on a live app can therefore change memberships for many people at once. Ask the Okta administrator and the Langfuse administrator to approve the same document before any change is made.

Clear names also matter during operations. When someone asks why access changed, the team must know which app authenticated the user and which app created or removed the membership. Verify this in a test organization before production. Assign a test user to the SCIM app and confirm the membership appears, confirm that sign-in works only through the OIDC app, then unassign the user and confirm the membership is removed while the user record remains. Check the self-hosted Enterprise license first, because Langfuse's SCIM endpoints require it. Record each test result against the documented apps so the same names carry into the production runbook.

The main risk in the first sync is that a user's organization role can be set by the SCIM roles attribute rather than by the role the person held before. Langfuse warns that SCIM deprovisioning and reprovisioning can overwrite a user's organization role with that attribute, and the attribute defaults to NONE. A user created through SCIM POST /Users without a roles value starts with no role. Any access the person had before therefore depends on what Okta sends at the moment the user is provisioned or reprovisioned.

Consider an illustrative case, not a record of any real deployment. A project lead holds a project-level role in a self-hosted Langfuse Enterprise instance. An administrator removes them from the Okta group assigned to the Langfuse SCIM app, and Langfuse removes their organization membership through DELETE /Users/{id}. The user record itself remains. Weeks later, the person is re-added to the group, but the roles attribute was never set in the Okta mapping. Langfuse recreates the membership with role NONE, so the project lead signs in, sees no projects they should manage, and cannot act until an administrator reassigns the role by hand.

The attribute has to be correct before provisioning is switched on because the role assigned during initial sync is the one every later deprovision and reprovision repeats. If the mapping is wrong at that stage, the error spreads to every user who changes group membership, and the fix becomes a manual reassignment across the organization with an unclear audit trail. Before enabling provisioning, decide which Okta groups map to which Langfuse roles, decide what a user outside all mapped groups should receive, and assign one owner to maintain that mapping. Confirm the exact role values your Langfuse version accepts in its SCIM and Org API documentation.

Run a dry run against a non-production Langfuse instance with a small set of test users in test groups. Confirm the role each test user receives after first provisioning, then remove and re-add one user and check that the role survives the cycle. Check that a user left outside every mapped group receives the role you intended and not NONE by accident. Verify that the SCIM credential is an organization-scoped API key and that the Enterprise license is active, since SCIM requires it for self-hosted use. Ask your Okta administrator to confirm which provisioning actions the SCIM app will send in your tenant, and record the results before the production group assignments change.

Run the full provisioning cycle on a small pilot group before you assign the SCIM application to the wider Okta group. The reason is the roles attribute. Langfuse's SCIM endpoints create a new user with the NONE role unless a roles attribute is provided, and a deprovision and reprovision can overwrite an existing organization role with that attribute's value, which defaults to NONE. A pilot lets you observe that behavior in your own tenant with a handful of accounts. Choose pilot users who cover each organization role you plan to assign, and write down each user's expected role, Okta group membership and Langfuse project access before the first sync. Those written expectations become the baseline that every later step is checked against.

Run the cycle in order and review Langfuse after every step. First, create: assign each pilot user to the SCIM application and confirm the user appears in the organization with the expected role. Second, change the role: alter the attribute or group that drives it in Okta, push the change, and confirm the membership role updates. Third, deprovision: unassign the user, confirm the organization membership is removed, and confirm the user account still exists, because a SCIM DELETE removes only the membership. Fourth, reprovision: assign the same user again and confirm the role matches the roles attribute and the value you recorded, not NONE. After the create and reprovision steps, sign in through the separate OIDC application, because SCIM does not set passwords and sign-in depends on that app.

Record enough to prove the roles attribute held through reprovisioning. For each step, log the time, the Okta action and resulting event, the pilot user's organization membership and role as shown in Langfuse, any project access, and the sign-in result. Where you can, keep the SCIM request and response, including the roles value sent and the status returned. Store the log with the pilot plan so an internal reviewer or external auditor can trace what changed and when. Keep the record factual: it shows what happened in your environment, but on its own it does not establish that a control operates effectively. Before the first run, confirm with Langfuse the exact attribute name and payload format for your version, and confirm the attribute mapping on the SCIM application in Okta.

Plan the rollback before the first test. Note the current organization membership and role for every pilot user, so you can restore values by hand if provisioning changes them unexpectedly. Keep at least one administrator with organization-level access who can edit memberships in Langfuse without depending on the SCIM path. Know how to pause provisioning by unassigning the pilot group from the SCIM application, and know how to rotate the organization-scoped API key that SCIM uses if that credential is exposed. Agree in advance who can halt the rollout and who must be told. If a reprovisioned user lands at NONE, stop, restore the recorded role, and repeat the cycle only after the cause is fixed and documented.