Just-in-Time Provisioning and Group Sync

Just-in-time (JIT) provisioning creates a Qualytics account the first time someone signs in through your Identity Provider (IdP). When group sync is enabled, that sign-in can also place the account on the Qualytics Teams that match the IdP groups the person belongs to. Nothing needs to be created in Qualytics ahead of time, and no separate synchronization service needs to run.

This page is written for administrators who want Qualytics Team membership to follow the directory groups they already maintain, such as Active Directory or Microsoft Entra ID security groups, Okta groups, Keycloak groups, or the equivalent group construct in another IdP.

What Happens at Sign-In

Every OIDC sign-in produces the following outcome. The first four rows always apply. The last row applies only when group sync is turned on.

Group sync deliberately does not do the following:

• It does not create Teams. A group with no matching Team is ignored.
• It does not remove anyone from a Team. See Keeping Membership Accurate Over Time.
• It does not set the platform role. Groups map to Team membership only, never to Member, Manager, or Admin.
• It does not assign datastores to Teams or set team permissions. Those stay under your control in Qualytics.
• It does not deactivate accounts when someone leaves a group.

Group Sync Compared With Directory Sync

Qualytics offers two ways to align Team membership with your directory. They solve the same problem with very different trade-offs.

How Group Matching Works

1. Your IdP presents a group listing in the claim you configured.
2. Qualytics trims surrounding spaces from each name and drops empty entries.
3. The resulting listing is recorded on the account, replacing whatever was recorded before.
4. Each name is compared against existing Team names, ignoring letter case. Data-Engineering, data-engineering, and DATA-ENGINEERING all match the same Team.
5. The person is added to every matching Team they are not already on. Nothing else changes.

flowchart TD
    A[User signs in via IdP] --> B{Group claim present?}
    B -- No --> C[Keep the previously recorded listing]
    B -- Yes --> D[Record the presented group names]
    D --> E{Group sync enabled?}
    E -- No --> F[Listing recorded for review only]
    E -- Yes --> G{Group name matches an existing Team?}
    G -- No --> H[Ignore the group]
    G -- Yes --> I{Already a member?}
    I -- Yes --> J[No change]
    I -- No --> K[Add the user to the Team]

When a Group Claim Is Missing or Empty

The difference between a missing claim and an empty one matters, because a misconfigured claim should not look like a directory that reports no memberships.

A missing claim never blocks sign-in. It shows up as an account with no recorded groups, which is the first thing to check when someone reports that they were not added to a Team.

When Changes Take Effect

The group listing is captured at sign-in and stays fixed for the life of that session. Adding someone to a directory group takes effect the next time they sign in, not while they are already signed in. To pick up a directory change immediately, have the person sign out and sign back in.

Step 1: Confirm What Your IdP Sends

Before you enable anything, confirm the exact claim name and the exact values your IdP puts in it. Many IdPs need an extra scope before they include groups at all, and several send group identifiers rather than group names.

You do not have to guess. Because the presented listing is recorded even while group sync is off, you can turn on the claim in your IdP first, have a test user sign in, and read back exactly what arrived. See Step 4.

Step 2: Create Matching Teams

Group sync never creates Teams, so every group you want honored needs a Team whose name matches it, ignoring letter case.

1. List the directory groups that should govern access in Qualytics.
2. Add a Team for each one, using the group name exactly as your IdP presents it.
3. Assign datastores and set the team permission for each Team. Group sync controls who is on a Team, never what that Team can reach.

Groups that have no matching Team are ignored, so an over-broad claim is harmless. Sending your entire directory group list is not a security problem by itself, but it does make the recorded listing noisy to review, and a Team created later with a colliding name will start receiving members at the next sign-in. Prefer a claim filtered to the groups that are relevant to Qualytics.

Step 3: Enable Group Sync

Group sync is off by default because Team membership can grant access to data, so an upgrade must never start adding people to Teams on its own. Enable it only after Step 1 and Step 2 are complete.

Self-Hosted

Set the following under secrets.oidc in your Helm values.yaml, then apply the change with the helm upgrade command from the OIDC Configuration Guide.

secrets:
  oidc:
    # Add any scope your IdP requires before it will send groups.
    oidc_scopes: "openid,email,profile,groups"
    # The claim name confirmed in Step 1. Defaults to "groups".
    oidc_user_groups_key: "groups"
    # Off by default. Turn on only after you have reviewed a real listing.
    oidc_group_team_sync_enabled: true

Setting the claim name alone does not grant any membership. It only starts recording what your IdP sends, which is the recommended way to trial this before the sync itself is enabled.

Step 4: Review What Your IdP Presented

The group listing recorded for each account is available through the Personal Account API in the oidc_groups field. Use it to confirm that the claim arrived, that the values are names rather than identifiers, and that they match your Team names.

curl -H "Authorization: Bearer $QUALYTICS_TOKEN" \
  "https://your-qualytics-domain/api/users?name=Jane"

Each user in the paginated results carries both what the IdP presented and the Teams the account currently belongs to:

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "role": "Member",
  "oidc_groups": ["Data-Engineering", "Finance-Analysts", "All-Employees"],
  "teams": [
    { "name": "Public", "permission": "Reporter" },
    { "name": "Data-Engineering", "permission": "Editor" }
  ]
}

Reading this example: Finance-Analysts was presented but produced no membership, which means no Team of that name exists yet. All-Employees was presented and ignored for the same reason. Listing users requires the Manager or Admin role. See the Personal Account API.

Keeping Membership Accurate Over Time

Group sync is add-only. This is the single most important thing to plan around, because it means a directory change that grants access is applied automatically while a directory change that revokes access is not.

Removing someone from a directory group has no effect on the Team they were already added to. They keep that Team membership, and the access it carries, until an administrator removes it in Qualytics.

Plan for two separate paths:

• Granting access is automatic. Add the person to the directory group and their next sign-in puts them on the matching Team.
• Revoking access is manual. Remove the person from the directory group, then remove their Team membership in Qualytics.

A Reconciliation Routine

Because the recorded group listing is refreshed at every sign-in, it is a live picture of the directory that you can compare against actual Team membership. Run this review on the cadence your access policy requires.

1. List users through the API and read oidc_groups alongside teams for each account.
2. Flag any Team membership that has no matching entry in oidc_groups. That is a membership the directory no longer justifies.
3. Confirm the exceptions. A membership granted deliberately in Qualytics, or one predating group sync, will also show up here and is legitimate.
4. Remove the memberships that remain by editing the user.
5. Deactivate the account for anyone who has left the organization. Removing a Team membership limits reach, but only deactivation ends access.

When to Use Directory Sync Instead

If your access policy requires that revoking a directory group revokes Qualytics access without an administrator acting, group sync is not sufficient on its own. Use Directory Sync, which manages the full lifecycle including removals, and leave group sync off.

Limitations

Troubleshooting

Related

• OIDC Authentication Configuration
• Directory Sync
• How Teams Work
• Team Best Practices
• How Personal Accounts Work