---
title: "Assignments"
description: "Choose which directory users and groups may sign in to each application."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assignments

An assignment allows a directory user, or every member of a directory group, to sign in to an
application. Nobody is assigned to a new application. Assignments are directory decisions, not
IAM policies: no policy grants sign-in to your application.

## The assignment list

Each application has one list of up to 1,000 assignments, each a user or a group:

```json
{
  "applicationId": "0192…",
  "assignments": [
    { "principalType": "group", "principalId": "0192…", "name": "engineering", "email": null, "resourceName": "ezgh:us-west-1:org_…:dir_…:dgp_…", "createdAt": "2026-10-01T09:00:00.000Z" },
    { "principalType": "user", "principalId": "0192…", "name": "Ada Lovelace", "email": "ada@acme.com", "resourceName": "ezgh:us-west-1:org_…:dir_…:usr_…", "createdAt": "2026-10-01T09:00:00.000Z" }
  ]
}
```

| Operation | Does |
| --- | --- |
| [ListAssignments](/sso-api/ListAssignments/) | Returns the whole list, with an `ETag`. |
| [UpdateAssignments](/sso-api/UpdateAssignments/) (`PUT`) | Replaces the whole list with `{ "assignments": [{ "principalType", "principalId" }, …] }` (0 to 1,000). |
| [AddAssignments](/sso-api/AddAssignments/) (`POST`) | Adds 1 to 100. One already there changes nothing. |
| [RemoveAssignments](/sso-api/RemoveAssignments/) (`DELETE`) | Removes 1 to 100. One not there changes nothing. |

- Writes take `If-Match` with the list's `ETag`. If the list changed since you read it, the write
  is `412 precondition_failed` and nothing changes. Without `If-Match` the write applies.
- Every user and group must be in the directory. More than 1,000 is `409 too_many_assignments`.
- Deleting a user or group removes its assignments.

In the console, use the application's **Assignments** tab. With the CLI:

```sh
ezgh sso assignments list Wiki
ezgh sso assignments add Wiki --group engineering --user ada@acme.com
ezgh sso assignments remove Wiki --user ada@acme.com
```

## When assignments are checked

Assignments, and group memberships, are read at every authorization request, code exchange,
refresh, userinfo call, introspection and SAML sign-in, so a change applies at once:

- Someone not assigned who tries to sign in sees an error page, and the application gets nothing
  (with `prompt=none`, `access_denied`). It's recorded in Trails as a failed
  `AuthorizeApplication` (`not_assigned`).
- Someone unassigned after signing in can't refresh their tokens: the code exchange or refresh
  revokes the grant. Access tokens already issued last until they expire, unless your API uses
  [introspection](/sso/oidc-endpoints#introspection).
- Someone not assigned who tries to sign in to a [SAML application](/sso/saml-applications)
  sees an error page, and the application gets nothing.
- The portal shows tiles only for applications the person is assigned to.
- For an application with [outbound provisioning](/sso/provisioning), assigning someone creates
  them at the application, and unassigning them deactivates them there.

With `groupsClaim: assigned` (the default), the `groups` claim lists only the person's groups
that are assigned to the application. See [OIDC applications](/sso/applications#scopes-and-claims).
A SAML application's `${user.groups}` attribute works the same way, with `groupsFilter`.

For an [EZGH app](/sso/ezgh-apps), assignments only decide who sees its portal tile. Using an EZGH
product is decided by IAM. The console application's assignments decide who sees the EZGH Console
tile and who may open the console; which bots they may use there is each bot's trust, in IAM (see
[Console access](/sso/console-access)).

Source: https://docs.ezghcloud.com/sso/assignments/index.mdx