GraphQL Tips and Best Practices

GraphQL allows for complex queries against the Turbot Guardrails API. Find the GraphQL reference page for more information. If you are new to GraphQL, check out our GraphQL 7 minute lab.

GraphQL best practices

GraphQL queries and mutation have two parts: the query itself and variables.

While it is possible to inline variables into the query, it is best practice to keep the query distinct from the variables. Dealing with templates to inject variables into a query is messy, especially when GraphQL can do that kind of merge for you.

Bad Query

query Profile {
  resource(id: "joe") {
    data
    metadata
    trunk {
      title
    }
    turbot {
      akas
      id
      tags
    }
  }
}

Here the date is placed directly inline, making the query less flexible.

Good Query

Use instead a query with variable input:

query Profile($id: ID!) {
  resource(id: $id) {
    data
    metadata
    trunk {
      title
    }
    turbot {
      akas
      id
      tags
    }
  }
}

And for this particular query type, you can use variables as follows:

{
  "id": "joe"
}

Expensive Queries

Some queries can become expensive in larger environments. For example, metadata.stats.total queries can be expensive in large environments. As an alternative method for checking for presence, one might put limit:1 in the query filter and replace

{
  metadata {
    stats {
      total
    }
  }
}

block with

items {
  ...
}

The advantage of limit:1 is that Guardrails only needs to grab a single row instead of getting all rows to generate the total.

GraphQL and Permission Grants

Administrators can query for all active grants in a Guardrails environment, create and activate grants, as well as remove grants all via the GraphQL API.

Get All Active Grants

To get a straight list of all the controls, you can use the following GraphQL query without any variables.

query GetListOfActiveGrants {
  activeGrants {
    items {
      grant {
        roleName
        identity {
          akas
        }
        level {
          title
          parentUri
        }
      }
      resource {
        akas
      }
      turbot {
        id
      }
    }
  }
}

This will return a list of entries that could be used by Calculated Policies or consumed by some other application that can manipulate JSON output.

Get All Active Grants For A Specific User(s)

You will use the above query but added to this query, we now have introduced a variable called $filter which will allow us to specify which users we are interested in.

query GetListOfActiveGrants($filter: [String!]) {
  activeGrants(filter: $filter) {
    items {
      grant {
        roleName
        identity {
          akas
        }
        level {
          title
          parentUri
        }
      }
      resource {
        akas
      }
      turbot {
        id
      }
    }
  }
}

If we want to return the results for a single user. We can use that users email address which is unique in Guardrails. For example, we want to see all active grants for user omero@turbot.com, we can use the following input:

{
  "filter": ["profile:omero@turbot.com"]
}

If we would like to additional users, for example bob@turbot.com, you can modify the variable as follows:

{
  "filter": ["profile:omero@turbot.com,bob@turbot.com"]
}

Get Individual Grant

To get a specific grant, you will have to determine the ID of that grant, which can be found by listing all the grants and using the turbot.id property.

query ActiveGrant($id: ID!) {
  activeGrant(id: $id) {
    validFromTimestamp
    validToTimestamp
    grant {
      identity {
        akas
      }
      level {
        title
        parent
      }
    }
  }
}

Here, we would like to list the grant that has the the specific id: 190591611773680

{
  "id": 190591611773680
}

Creating Grants

To create grants, one can use the GraphQL mutation createGrant. NOTE Any new grant that you create will have to activated as all grants are created but are by default inactive as a safety feature.

mutation CreateGrant($input: CreateGrantInput!) {
  createGrant(input: $input) {
    turbot {
      id
    }
  }
}

Example input variable for creating grants:

{
  "input": {
    "type": "tmod:@turbot/aws#/permission/types/aws",
    "level": "tmod:@turbot/turbot-iam#/permission/levels/operator",
    "resource": "tmod:@turbot/turbot#/",
    "identitySearch": {
      "directory": "226714953374521",
      "type": "USER",
      "identity": "eee@jf.turbot.local"
    }
  }
}

Take note of turbot.id as this will be used to activate the grant using the activate grant mutation.

Further details on input parameters:

type

For AWS grant use the type: tmod:@turbot/aws#/permission/types/aws For GCP grant use the type: tmod:@turbot/gcp#/permission/types/gcp For Azure grant use the type: tmod:@turbot/azure#/permission/types/azure For Guardrails grant use the type: tmod:@turbot/turbot-iam#/permission/types/turbot

level

For level user: tmod:@turbot/turbot-iam#/permission/levels/user For level operator: tmod:@turbot/turbot-iam#/permission/levels/operator For level admin: tmod:@turbot/turbot-iam#/permission/levels/admin For level metadata: tmod:@turbot/turbot-iam#/permission/levels/metadata For level owner: tmod:@turbot/turbot-iam#/permission/levels/owner For level readonly: tmod:@turbot/turbot-iam#/permission/levels/readonly For level superuser: tmod:@turbot/turbot-iam#/permission/levels/superuser

resource

This is the resource that you want to attach to. You can find the AKA of a resource using the Guardrails UI.

For an AWS account the resource AKA is: arn:aws:::<account_number> For a GCP account the resource AKA is: gcp://cloudresourcemanager.googleapis.com/projects/<project_name> For an Azure account the resource AKA is: azure:///subscriptions/<subscription_id> At the Turbot level the AKA is: tmod:@turbot/turbot#/

identitySearch.directory

This holds the details of the Directory where the Users Profile exists

identitySearch.type

This is either GROUP or USER

identitySearch.identity

This is usually the User's email address

Activate Grants

You can activate grants using the mutation:

mutation ActivateGrant($input: ActivateGrantInput!) {
  activateGrant(input: $input) {
    turbot {
      id
    }
  }
}

The id of the grant is given when creating the grant. Use this id with the property input.grant. You will also need to configure at what resource you want to activate the grant. This is the same as the resource that was used when creating the grant.

An example input is as follows

{
  "input": {
    "grant": "225901139222587",
    "resource": "tmod:@turbot/turbot#/"
  }
}