SSO User and Group Mapping

When someone signs in with SSO, the IdP sends user attributes, and often group memberships, in the SAML assertion or OIDC claims. Mapping is how you tell Descope what to do with that data: which fields become user profile attributes, which groups become roles on the tenant, and (if you use Fine-Grained Authorization) which groups should create FGA relations for that user.

The same maps apply when:

• The user signs in with SSO (including JIT create/update)
• SCIM syncs groups for that SSO config (RBAC role maps, with FGA maps applied on SSO login)

What You Can Map

RBAC and FGA maps don't depend on each other. One IdP group can grant a role, an FGA relation, or both.

SAML IdPs usually send a multi-value groups attribute (or something similar). OIDC doesn't standardize groups, so enable a groups (or custom) claim on the IdP, then set Groups attribute name in Descope to that claim. See OIDC → Group claims for details. Both SAML and OIDC support RBAC and FGA group maps. Protocol notes: Authorization with SSO providers.

Groups to Roles

After SSO (and after SCIM group sync, if you use it), a user in Engineering has the Developer Team role on that tenant.

Groups to FGA Relations

If you already use FGA (Descope's ReBAC / ABAC system), you can map IdP groups the same way you map them to roles, except the result is a relation instead of a role.

Example: a user in the IdP's Engineering group signs in, and Descope creates a relation like "this user is a member of the engineering team," using whatever schema you've defined for the project. From then on, your app can check that relation the same way it would for any other FGA tuple you created by hand.

You need a schema on the project before this works. If there isn't one, login fails with SchemaDoesNotExist because there's nothing for the mapping to attach to. Start with Defining a schema and implementing it.

This is separate from group → role mapping. You can use one, the other, or both for the same group.

What A Mapping Looks Like

In FGA terms, a relation says: this user has this relation to this resource, under a type (namespace) from your schema.

An SSO FGA map stores everything except the user. Descope fills in the user at login. For each IdP group name, you list one or more entries with:

Those maps live on the tenant's SSO settings for SAML and for OIDC (fgaMappings in the Management tenants SSO API). In the Console and Management API you'll see FGA mappings. Some backend events still say ReBAC groups mappings (rebacGroupsMappings), which is the same feature.

So if you map IdP group Engineering → namespace team, relation member, resource engineering, then on login Descope creates the same kind of relation you'd get from calling Create Relations with that user as the target.

Default Relations (Optional)

You can also set a fallback list, defaultReBACRelations, with the same shape (namespace / relation / resource). Descope only uses it when the tenant has no group-specific FGA maps at all. On that path, if a resource is set to {{tenantID}}, Descope replaces it with the real tenant ID at login.

For SAML tenants, configFGATenantIDResourcePrefix and configFGATenantIDResourceSuffix on that tenant's SSO settings control what {{tenantID}} expands to: the resolved resource is prefix + tenantID + suffix. These two fields aren't available on OIDC settings.

How to Set Up FGA Group Mapping

1. Create (or confirm) an FGA schema for the project.
2. Configure SSO for the tenant (SAML or OIDC).
3. Add FGA group maps on that SSO config:
   • Console: tenant → Authentication Methods → SSO → SSO Mapping → FGA Group Mapping.
   • API: set fgaMappings when you call the SAML/OIDC tenant SSO settings endpoints.
4. Optionally set defaultReBACRelations if you want the fallback described above.
5. Sign in with a test user and check the relation (or inspect it in the Console).

Example

After SSO, Alice has a member relation to team / engineering (and an editor relation on doc / handbook if she's also in Doc Editors). Your app checks those the same way as any other FGA relation.

SSO Setup Suite

Your customer's admin can set attribute and group maps (including FGA, when you've enabled it for the suite) in the Setup Suite, then run the connection test. See Setup Suite attribute mapping.

Management SDK / API

Automate maps with Configure SSO SDKs or the Management tenants SSO API. For FGA, use the fgaMappings field on the SAML/OIDC settings payload.

from descope import (
    SSOSAMLSettings,
    FGAGroupMapping,
    FGAGroupMappingRelation,
)

settings = SSOSAMLSettings(
    idp_url="https://idp.example.com/saml",
    idp_entity_id="my-entity-id",
    idp_cert="<certificate>",
    fga_mappings={
        "Engineering": FGAGroupMapping(
            relations=[
                FGAGroupMappingRelation(
                    namespace="team",
                    relation_definition="member",
                    resource="engineering",
                ),
            ],
        ),
    },
    # Optional, SAML only: customize what the `{{tenantID}}` placeholder resolves to
    config_fga_tenant_id_resource_prefix="org_",
    config_fga_tenant_id_resource_suffix="",
)

descope_client.mgmt.sso.configure_saml_settings(
    tenant_id="tenant-id",
    settings=settings,
    redirect_url="https://your.domain.com",
)

samlSettings := &descope.SSOSAMLSettings{
    IdpURL:      "https://idp.example.com/saml",
    IdpEntityID: "my-entity-id",
    IdpCert:     "<certificate>",
    FgaMappings: map[string]*descope.FGAGroupMapping{
        "Engineering": {
            Relations: []*descope.FGAGroupMappingRelation{
                {Namespace: "team", RelationDefinition: "member", Resource: "engineering"},
            },
        },
    },
    // Optional, SAML only: customize what the `{{tenantID}}` placeholder resolves to
    ConfigFGATenantIDResourcePrefix: "org_",
    ConfigFGATenantIDResourceSuffix: "",
}
err := descopeClient.Management.SSO().ConfigureSAMLSettings(context.Background(), "tenant-id", samlSettings, "https://your.domain.com", nil, "")

Multiple IdPs on One Tenant

Each SSO profile has its own maps. Configure them per ssoId. See Multiple SSO providers.

IdP-Side Checklist

• Send the attribute and group names Descope expects (they have to match what you configured).
• Entra ID: prefer stable group IDs over display names if groups get renamed often. See SSO troubleshooting.
• Okta: make sure users/groups are assigned to the app. Assignments versus Push Groups is a common mix-up on that same page.

Verify and Troubleshoot

1. Sign in with a known test user.
2. Check the login event in Audits (SSO audit fields).
3. For RBAC: confirm the user's roles on the tenant match the IdP groups you expected.
4. For FGA: check the relations (or look them up in the Console).
5. If groups never show up, check IdP app assignment and the Groups attribute name on the SSO config.

More: SSO troubleshooting.

Related

• JIT provisioning
• SCIM
• ReBAC overview · Define a schema · Create relations
• Authorization with SSO providers
• SSO troubleshooting