Users, roles, & access control
Last updated
Last updated
AirQL currently supports Google as an identity provider. This means that end users with a Google account can be authenticated by AirQL, and access control will be enforced according to their Google identity.
Once authenticated by Google, AirQL will issue OAuth2 credentials that can then be used to authenticate AirQL API requests. In practical terms this means that AirQL is an OAuth2 provider and is compatible with standard OAuth2 client libraries.
AirQL users can belong to any number of roles defined in the UI. These roles are sets of permissions which define access to tables, fields, and rows. Here's an example of three roles being configured on two tables:
Here, role1 has access to all fields in Table2, but no fields in Table1. role2 has access only to field1 on Table1, and field1 on Table2. role3 has access to all fields on both tables.
You can manage a users' roles using the user form accessible from the Users tab in the AirQL UI:
Note the admin role. This role was defined when the base was added to AirQL. Users that are granted the admin role have read and write access to all fields in all tables.
Field-level access control for each role is configured in the permissions form accessible from the Tables tab in the AirQL UI. Here's an example of configuring field access for the user role on an Employee table:
Note that granting field access currently means gives grantees read and write access to the field.
When AirQL services an API request, it determines on a field-by-field basis whether the requesting user has access to the fields being requested. As long as the user belongs to a role that has access to a field, then the request will be serviced as expected:
On the other hand, fields that are not accessible to the requesting user will produce GraphQL errors:
Row-level access control in AirQL can be configured using Airtable formulas. When querying rows from Airtable for a particular table and role, the configured formula will be applied as a filter to the result set. Only the rows for which the formua evaluates to a TRUE will be returned, as shown below:
The filter formula for a particular table and role can be set on the permissions form shown here.
Filter formulas can reference any fields in the table using the usual {Field Name} syntax. They can also use all of the usual formula functions. Additionally, the logged in users' email can be referenced using the special AIRQL_USER_EMAIL field name. This makes it possible to filter out results that aren't associated with the currently logged in user. For example:
This formula would restrict results to those where the Email field matches the logged in users' email address.
In the event that multiple roles have filter formulas configured for a single table, rows in the union of all formulas for the requesting users' roles will be returned.
Since users can be granted multiple roles, and roles may have overlapping or disjoint permissions sometimes you need to override the role that's applied for a particular query.
AirQL accepts an HTTP header called X-AirQL-Roles which should contain a comma delimited list of role names. When applying permissions, only the subset of roles specified in the header that the requesting user belongs to will be considered.
For example, if a user has the user and manager roles, and you wish to fetch only those rows accessible to any user then you would use the header X-AirQL-Roles: user.
