Skip to main content
Version: v3.x

Role Emulation

Introduction​

You can configure authentication to allow certain roles to emulate other roles. This can be useful during development to test access-control rules without setting up authentication.

To set up role emulation, the AuthConfig Hasura metadata object accepts a field called allowRoleEmulationBy.

When allowRoleEmulationBy is set up, Hasura will check for the value of the x-hasura-role session variable which is returned in the webhook or JWT response to be equal to the value set in the allowRoleEmulationBy. If the values are equal, then role emulation will be enabled for that request.

When role emulation is enabled for a request, the session variables, including the role, will be used from the HTTP request headers instead of from the JWT or webhook.

Role emulation scenario setup​

In the example below, we set up role emulation for the api_admin role, allowing an api_admin to emulate any other role:

---
kind: AuthConfig
version: v1
definition:
  allowRoleEmulationBy: api_admin
  webhook:
    webhookUrl: https://myauth.service.com/validate-request

Then, the following GraphQL request is made with some session variables in the headers:

POST /graphql HTTP/2.0
Content-Type: application/json
Authorization: Bearer <user-token>
x-hasura-role: author
x-hasura-author-id: 2

{
  "query": "query GetAuthor { author { id name } }",
  "variables": null,
  "operationName": "GetAuthor"
}

The session variables actually used in this request will depend on the values provided in the request headers and the values returned by the authentication webhook.

Role emulation scenario 1​

Now, let's assume the authentication webhook responds with the following session variables for the request:

{
  "x-hasura-role": "api_admin"
}

Then, because the api_admin role is allowed to emulate other roles, (as per the allowRoleEmulationBy: api_admin value in our AuthConfig) the GraphQL request will be executed as the author role, because the x-hasura-role: author value is set in the headers of the request, along with x-hasura-author-id: 2.

i.e. the query will be executed with:

{
  "x-hasura-role": "author",
  "x-hasura-author-id": 2
}

Role emulation scenario 2​

If the authentication webhook response is as follows:

{
  "x-hasura-role": "api_admin",
  "x-hasura-author-id": 1
}

Then even in this case, because the api_admin role is making the request and is allowed to emulate other roles, the GraphQL request will be executed as the author role, as that is the role stipulated in the request headers.

Also, the value of the session variable x-hasura-author-id will be 2 and not 1, as that is the value stipulated in the request headers.

i.e. the query will be executed with:

{
  "x-hasura-role": "author",
  "x-hasura-author-id": 2
}

Role emulation scenario 3​

To illustrate an unsuccessful emulation scenario; if the webhook response were the following:

{
  "x-hasura-role": "user",
  "x-hasura-author-id": 1
}

Then, the GraphQL query will be executed as the user role and only the session variables from the authentication webhook response will be considered.

This is because the user role is not allowed to emulate other roles via HTTP request headers. All session variables for this request will be extracted from the authentication webhook response

i.e. the query will be executed with:

{
  "x-hasura-role": "user",
  "x-hasura-author-id": 1
}
Loading...