# Source: https://docs.hypermode.com/dgraph/graphql/security/rbac-rules.md

# RBAC Rules

> Dgraph support Role Based Access Control (RBAC) on GraphQL API operations.

<Info>
  We're overhauling Dgraph's docs to make them clearer and more approachable. If
  you notice any issues during this transition or have suggestions, please
  [let us know](https://github.com/hypermodeinc/docs/issues).
</Info>

Dgraph support Role Based Access Control (RBAC) on GraphQL API operations: you
can specify who can invoke query, add, update and delete operations on each type
of your GraphQL schema based on JWT claims, using the `@auth` directive.

To implement Role Based Access Control on GraphQL API operations :

1. Ensure your have configured the GraphQL schema to [Handle JWT tokens](./jwt)
   using `# Dgraph.Authorization` This step is important to be able to use the
   [JWT claims](./overview#jwt-claims)
2. Annotate the Types in the GraphQL schema with the `@auth` directive and
   specify conditions to be met for `query`, `add`, `update` or `delete`
   operations.

The generic format of RBAC rule is as follow

```graphql
type User @auth(
    query: { rule:  "{$<claim>: { eq: \"<value>\" } }" },
    add: { rule:  "{$<claim>: { in: [\"<value1>\",...] } }" },
    update: ...
    delete: ...
)
```

RBAC rule supports `eq` or `in` functions to test the value of a
[JWT claim](./overview#jwt-claims) from the JWT token payload.

The claim value may be a string or array of strings.

For example the following schema has a @auth directive specifying that a delete
operation on a User object can only be done if the connected user has a 'ROLE'
claim in the JWT token with the value "admin" :

```graphql
type User @auth(delete: { rule: "{$ROLE: { eq: \"admin\" } }" }) {
  username: String! @id
  todos: [Todo]
}
```

The following JWT token payload will pass the test (provided that
Dgraph.Authorization is configured correctly with the right namespace)

```json
{
  "aud": "dgraph",
  "exp": 1695359621,
  "https://dgraph.io/jwt/claims": {
    "ROLE": "admin",
    "USERID": "testuser@dgraph.io"
  },
  "iat": 1695359591,
  ...
}
```

The rule is also working with an array of roles in the JWT token:

```json
{
  "aud": "dgraph",
  "exp": 1695359621,
  "https://dgraph.io/jwt/claims": {
    "ROLE": ["admin","user"]
    "USERID": "testuser@dgraph.io"
  },
  "iat": 1695359591,
  ...
}
```

In the case of an array used with the "in" function, the rule is valid is at
least one of the claim value is "in" the provided list.

For example, with the following rule, the previous token will be valid because
one of the ROLE is in the authorized roles.

```graphql
type User
  @auth(delete: { rule: "{$ROLE: { in: [\"admin\",\"superadmin\"] } }" }) {
  username: String! @id
  todos: [Todo]
}
```

## rules combination

Rules can be combined with the logical connectives `and`, `or` and `not`. A
permission can be a mixture of graph traversals and role based rules.

In the todo app, you can express, for example, that you can delete a `Todo` if
you are the author, or are the site admin.

```graphql
type Todo
  @auth(
    delete: {
      or: [
        { rule: "query ($USER: String!) { ... }" } # you are the author graph query
        { rule: "{$ROLE: { eq: \"ADMIN\" } }" }
      ]
    }
  )
```

## claims

Rules may use claims from the namespace specified by the
[# Dgraph.Authorization](./jwt) or claims present at the root level of the JWT
payload.

For example, given the following JWT payload

```json
{
   "https://xyz.io/jwt/claims": [
      "ROLE": "ADMIN"
   ],
  "email": "random@example.com"
}
```

If `https://xyz.io/jwt/claims` is declared as the namespace to use, the
authorization rules can use `$ROLE` but also `$email`.

In cases where the same claim is present in the namespace and at the root level,
the claim value in the namespace takes precedence.

## `@auth` on Interfaces

The rules provided inside the `@auth` directive on an interface will be applied
as an `AND` rule to those on the implementing types.

A type inherits the `@auth` rules of all the implemented interfaces. The final
authorization rule is an `AND` of the type's `@auth` rule and of all the
implemented interfaces.