> For the complete documentation index, see [llms.txt](https://docs.quilt.bio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quilt.bio/quilt-platform-administrator/advanced/sso-permissions.md).

# SSO Permissions Mapping

> This feature requires Quilt Platform version 1.54.0 or higher

## Overview

This feature allows Quilt admin to configure what roles and admin flag value are assigned to the user who logs in via SSO based on the user's ID token claims.

The configuration can be set with `quilt3.admin.sso_config.set()` or with admin UI.

![admin UI for setting SSO permissions mapping](/files/55ak1nc94cTYSisKjO92)

> Note: Roles used by configuration can't be removed or renamed.

> Note: The user who sets the configuration will never have their admin flag revoked.

> Note: After configuration is set, any user who logs in via SSO can't be manually assigned roles or admin permissions.

## Configuration

The configuration file is to be written in YAML and is defined by [this JSON Schema](https://github.com/quiltdata/quilt/blob/master/shared/schemas/sso-config-1.0.json) which includes descriptions of all the fields.

> Warning: In schemas don't forget to add claims you want to check to `required`, because otherwise the schema will match any ID token even if these claims are missing.

> Note: By default, mappings are evaluated in order and **only the first matching mapping is applied** — to assign multiple roles to a user this way, include all roles in the `roles` array of a single mapping. Alternatively, set `union_roles: true` at the top level of the config (Quilt Platform 1.69+) to grant the union of roles from **all** matching mappings; users can switch between the assigned roles via the role switcher, and any role no longer in the match set is revoked on next login.

### Example

```yaml
version: "1.0"
default_role: ReadQuiltBucket
union_roles: true
mappings:
  - schema:
      type: object
      properties:
        email:
          const: admin@example.com
      required:
        - email
    roles:
      - AdminTools
    admin: true
  - schema:
      type: object
      properties:
        groups:
          type: array
          contains:
            const: rw
      required:
        - groups
    roles:
      - ReadWriteQuiltBucket
```

By default (or with `union_roles: false`), only the first matching mapping applies — the `admin@example.com` user above would receive `AdminTools` only. With `union_roles: true`, that same user is granted both `AdminTools` and `ReadWriteQuiltBucket` (admin flag true) and can switch between them via the role switcher; a user with group `rw` only is granted `ReadWriteQuiltBucket` in either mode.

> Note: Users matching no mapping receive the `default_role` (`ReadQuiltBucket` in this example). Their admin flag is unchanged.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.quilt.bio/quilt-platform-administrator/advanced/sso-permissions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.