> For the complete documentation index, see [llms.txt](https://docs.opendatadiscovery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opendatadiscovery.org/configuration-and-deployment/enable-security/authorization/roles.md). # Roles A **Role** is a named bundle of permissions. ODD Platform has two distinct kinds of Role — **User roles** (derived from the auth chain at sign-in time) and **Owner roles** (operator-curated bundles attached to Owner entities) — and a precedence rule that resolves which kind wins for a given signed-in user. ## User roles There are two user roles: * `USER` — a regular user with no permissions by default. * `ADMIN` — an administrator with every permission. User-role assignment is derived from your authentication mode's configuration: the platform inspects the auth-mode-specific group / role / principal mapping (Cognito groups, GitHub teams, Azure roles, LDAP groups, Google admin-principals, etc.) at sign-in time and assigns either `ADMIN` or `USER` accordingly. For the full per-provider matrix of how admin promotion works, see [Admin promotion across providers](/configuration-and-deployment/enable-security/admin-promotion.md). ## Owner roles Owner roles are operator-curated bundles attached to Owner entities, managed at `Management → Roles`. Unlike User roles (two fixed values: `ADMIN` / `USER`), Owner roles are arbitrary — operators define them per deployment and compose the permissions each role bundle should carry. ### Attaching a Role to an Owner Role-to-Owner attachment happens on the `Management → Owners` surface — open the Owner row, edit it, and pick the Roles to attach. See [Owners → Owner roles](/configuration-and-deployment/enable-security/authorization/owners.md#owner-roles) for the operator workflow. The `ROLE_CREATE` / `ROLE_UPDATE` / `ROLE_DELETE` permissions gate role-bundle authoring; the `OWNER_UPDATE` permission gates the role-attachment action itself (it is a write to the Owner entity). ### Precedence: Owner roles override User roles When a signed-in user is bound to an Owner (via the [User-owner association](/configuration-and-deployment/enable-security/authorization/user-owner-association.md) workflow) **and that Owner carries at least one role**, the user's effective permissions come from the **Owner's** roles — not from the User role the auth chain assigned at sign-in. A user who signed in as `ADMIN` and then binds to an Owner that carries only a `Data Engineer` role **loses** the ADMIN privilege and runs with the Data Engineer permission bundle. **The override is conditional on the Owner having roles.** If the bound Owner has **no roles attached**, the platform falls back to the User role the auth chain assigned at sign-in — so binding to a zero-role Owner does *not* strip a signed-in `ADMIN`'s privileges; that user keeps ADMIN. The override applies only when the Owner's role set is non-empty. For a non-empty Owner role set the override is permanent for the lifetime of the binding: only an unbind (or a re-bind to a different Owner) restores or changes the effective permission set. {% hint style="danger" %} **Under `auth.type=DISABLED` authorization is not enforced at all.** Neither User roles nor Owner roles are consulted, and every request runs unrestricted — regardless of any Owner binding or role attachment. The precedence rules above take effect only when authentication is enabled (`LOGIN_FORM`, `OAUTH2`, or `LDAP`). `DISABLED` is the shipped default; see [Disable authentication](/configuration-and-deployment/enable-security/authentication/disabled-authentication.md) and switch `auth.type` to an enforced mode before exposing the platform on any reachable network. {% endhint %} ### Setting up an initial admin To set up a signed-in user who should have full ADMIN privileges through the catalog side, do **both** halves explicitly: 1. **Create an Owner with an ADMIN-equivalent Role bundle attached.** Either create a new Role on Management → Roles that carries `ALL` permissions, or pick an existing ADMIN-equivalent Role; then create the Owner on Management → Owners with that Role attached. Skipping this step and trying to "rely on" the user's sign-in ADMIN authority does not work once the user binds to any Owner that lacks ADMIN — the precedence rule above strips the auth-mode ADMIN at bind time. 2. **Bind the user to that Owner.** The recommended admin path is the **Create association** button on Management → Associations (gated by `OWNER_RELATION_MANAGE`) — this is the admin-direct-bind path that writes the binding immediately, without going through the request-and-approve workflow. See [User-owner association → Creating a binding directly](/configuration-and-deployment/enable-security/authorization/user-owner-association.md#creating-a-binding-directly-create-association) for the full form fields and behaviour. The sequence matters: bind the user to an Owner that already carries the ADMIN role bundle. If you bind first and attach the Role second, the binding is effective immediately and the user runs without ADMIN during the gap. ## Where to next * [Permissions](/configuration-and-deployment/enable-security/authorization/permissions.md) — the catalog of permission keys you can bundle into Role definitions. * [Policies](/configuration-and-deployment/enable-security/authorization/policies.md) — the JSON permission grants attached to owners through roles; note that **deleting a policy is blocked while any role is still bound to it** — detach it from every role first (full note on that page). * [Owners](/configuration-and-deployment/enable-security/authorization/owners.md) — how Owner entities work and the per-page caveat list for Owner CRUD. * [User-owner association](/configuration-and-deployment/enable-security/authorization/user-owner-association.md) — the binding workflow that triggers the Owner-role-supersedes-User-role precedence. * [Admin promotion across providers](/configuration-and-deployment/enable-security/admin-promotion.md) — for the per-auth-mode story of how the User role is initially assigned. --- # 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, and the optional `goal` query parameter: ``` GET https://docs.opendatadiscovery.org/configuration-and-deployment/enable-security/authorization/roles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.