Skip to main content
Version: v3.x beta

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 user role, allowing a user to emulate any other role:

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

Then, the following GraphQL request is made:

POST /graphql HTTP/2.0
Content-Type: application/json
x-hasura-role: author
x-hasura-author-id: 2

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

This request will be executed normally using the author role and access-control rules related to the author role will be applied to the request, for example: returning only the id and name fields of the author with id 2.

Role emulation scenario 1​

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

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

Then, because the user role is allowed to emulate other roles, (as per the allowRoleEmulationBy: user 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.

Role emulation scenario 2​

If the authentication webhook response is as follows:

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

Then even in this case, because the user 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.

Thus, the value of the session variable x-hasura-author-id will be 2 and not 1.

Role emulation scenario 3​

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

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

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

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

Therefore, in this case, the value of the session variable x-hasura-author-id will be 1 as returned by the authentication webhook response and not 2 as specified in the request headers.

Loading...