Groups and app access

Create groups, manage members, restrict applications to groups, and use groups to drive MFA, password policy and the groups claim in tokens.

Groups are the unit of access management in the directory: they decide which applications a user can sign in to, which users must use MFA, and what appears in the groups claim of tokens and SAML assertions.

How groups work

A group is a flat, named set of users inside your organization: a name, an optional description, an optional "require MFA" flag, and members. Managing groups requires the group management permission; every mutation is audited (admin.group.* events).

curl -sS -X POST https://accounts.obexal.com/v1/admin/groups \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Finance","description":"Finance team","requireMfa":false}'
# 201 -> {"group":{"id":"<groupId>","name":"Finance","description":"Finance team","requireMfa":false,"memberCount":0}}

GET /v1/admin/groups lists groups, PUT /v1/admin/groups/{id} updates one, DELETE /v1/admin/groups/{id} deletes it along with its memberships and app assignments.

Manage members

Members are added and removed individually, by user id:

curl -sS -X POST https://accounts.obexal.com/v1/admin/groups/<groupId>/members \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"userId":"<userId>"}'
# 200 -> {"status":"ok"}

GET /v1/admin/groups/{id}/members returns the members (id and email); DELETE /v1/admin/groups/{id}/members/{userId} removes one. The user must already exist in the directory: create accounts through invitations or inbound SCIM.

Restrict an application to groups

By default, an application with no group assigned is open to every user of the organization (this keeps existing apps working when you start adopting groups). As soon as at least one group is assigned, the application is restricted: only members of an assigned group can sign in to it.

curl -sS -X POST https://accounts.obexal.com/v1/admin/groups/<groupId>/apps \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"clientId":"app_a1b2c3"}'
# 200 -> {"status":"ok"}

The check runs when the OIDC authorization code is issued: a user outside the assigned groups gets an OAuth access_denied error and no code is ever created. The employee portal follows the same model: GET /v1/me/apps (the "My Apps" page) lists exactly the applications assigned through the user's groups, with the group that grants each one.

The groups claim

When a user belongs to at least one group, the ID token carries a groups claim with the group names (no extra scope required; the claim is omitted when the user has no group):

{
  "sub": "u_7f3a9c",
  "aud": "app_a1b2c3",
  "email": "alice@example.eu",
  "groups": ["Finance", "Managers"]
}

SAML assertions issued by Obexal as IdP carry the same names in the eduPersonAffiliation attribute. The claim is not present in access tokens or the userinfo response. Because the claim carries names, renaming a group changes what downstream applications receive.

Group policies

Two sign-in policies are group-driven:

• Require MFA: set "requireMfa": true on a group and every member must complete MFA at sign-in, in addition to any organization-wide MFA mandate.
• Password policy overrides: a group can carry a stricter password policy than the organization's. GET /v1/admin/password-policy/groups lists overrides, PUT /v1/admin/password-policy/groups/{groupId} sets one, DELETE removes it. When a user belongs to several groups, the strictest value wins field by field; an override can only harden the tenant policy, never weaken it.

Limits

• No nested groups: a group contains users, never other groups.
• Group memberships are not manageable through SCIM (the inbound server is Users-only).
• App assignment is by OAuth client_id, one application at a time.