How to map provider groups

How to map provider groups#

Let a provider grant local group membership, and decide which of its groups mean anything here.

Nothing happens until you say so: the group map starts empty, and an empty map grants nothing.

1. Tell the site where the groups arrive#

On the provider's Groups tab, set Groups arrive in the claim.

Provider

Claim

Keycloak

groups, once a Group Membership mapper exists

Okta

groups

Microsoft Entra ID

groups, once configured in the app manifest

A Plone site running the server layer

groups

GitHub, magic link

none—these drivers send no groups

groups is the default. Use a dotted path for a provider that nests them, such as realm_access.roles.

2. Map the groups you want#

Fill in the group map: one row per provider-side group name, each pointing at a local group id.

Three rules make this safe to leave running:

  • A name with no row grants nothing, and no group is ever created. A group claim is whatever the provider's directory happens to be called, so minting local groups from it would let anyone who can name a group at the far end create one here.

  • A row pointing at a group this site does not have is skipped and logged.

  • Every login reconciles, so a membership revoked at the provider stops granting anything here without anyone editing the site.

A login only ever takes back what that same provider granted. The identity record remembers each provider's own grant, so a group you granted by hand survives every sign-in, and two providers cannot revoke each other's grants.

3. Optionally, restrict who may sign in#

Leave Only these groups may sign in empty and anybody the provider authenticates may sign in.

Name groups in it and a sign-in is refused unless the provider says the person is in one of them.

An entry matches either a name the provider sends or a local group id the map turns one into, so write the policy in whichever vocabulary is clearer. The cost of accepting both is that an entry alone does not say which one it was read as, which is why a refusal records both.

This is checked on every sign-in, not only the first. Somebody removed from the group at the provider stops getting in, and an account created before you wrote the policy is held to it like any other.

Warning

This needs a group claim.

A provider whose driver has no groups at all—GitHub, magic link—sends none, so a list here refuses everybody. The log says so in as many words rather than reporting a group mismatch, because the mistake is in the configuration rather than in the directory.

The person refused is told only that the sign-in failed. Naming the group they are missing would tell anyone who can reach the login page which groups matter here. The reason goes to the audit trail, which needs Manage portal to read.

Keep the provider, decide groups yourself#

Switch off Let this provider set group membership to sign people in with the provider while deciding membership here.

A site may trust a provider to say who somebody is without trusting it to say what they may do, and group membership is usually what grants permissions.

Groups the provider already granted stay. Taking those away is a separate decision, and one to make deliberately rather than at the next login.

It is per provider, so refusing one is not refusing all of them.

Verify#

  1. Sign in with an account that is in a mapped group at the provider.

  2. The local group appears in that user's membership.

  3. Remove the account from the group at the provider, sign out, sign in again.

  4. The local group is gone.

  5. A group you granted by hand is still there.

Taking grants back#

Note

Clearing a map does not strip the groups it had granted.

Clearing is at least as likely to mean "I am rewriting this" as "revoke everything", so a provider with an empty map touches no membership at all.

To take its grants back, empty the map's values rather than the map, and let one login reconcile.

Next steps#

Contents