The @requiresScopes directive declares a GraphQL definition to require the agent (person, service, or device) to possess certain permissions. Lack of permissions will yield an authorization error.
The "scopes" argument requires an array (GraphQL List) of nested arrays.
The outmost array represents a set of OR scopes.
Each nested array sibling represents a set of AND scopes.
Each element in the AND scopes array should be an "openfed__Scope" scalar, which is an instance of permissions as defined in your authentication token. For example, "read:field".
OR Scopes
Consider the following @requiresScopes declared on Query.fieldOne:
type Query {
fieldOne: String! @requiresScopes(scopes: [["read:field"], ["read:scalar"]])
}
If an agent wished to select Query.fieldOne, it would require EITHER the "read:field" permission OR the "read:scalar" permission.
AND Scopes
Consider the following @requiresScopes declared on Query.fieldTwo
type Query {
fieldTwo: String! @requiresScopes(scopes: [["read:field", "read:scalar"]])
}
If an agent wished to select Query.fieldTwo, it would require BOTH the "read:field" permission and the "read:scalar" permission. Lack of one or both would return an authorization error.
Combining OR and AND Scopes
Consider the following @requiresScopes declared on Query.fieldThree
If an agent wished to select Query.fieldThree, it would require at least one of the following sets of scopes: (("read:field" AND "read:scalar") OR ("read:query" AND "read:private") OR ("read:all"))
Declaration
The @requiresScopes directive can be declared on enums, field definitions, interfaces, objects, and scalars. However, there are some differences between declaration on leaf definitions and parent definitions.
Declaration on leaf definitions (enums and scalars)
When @requiresScopes is declared on a leaf definition, the @requiresScopes directive (including its scopes) will be applied to all field definitions whose named type name (the innermost response type name) is the respective leaf definition within that subgraph.
If the same leaf definition is defined in another subgraph without @requiresScopes, the corresponding field definitions unique to that that subgraph will be unaffected. But note that @requiresScopes could be applied to those field definitions through other means.
If at least one instance of a shared field is declared with @requiresScopes, that field definition will be declared with @requiresScopes in the federated graph (see Federation).
Consider the following example:
When @requiresScopes is declared on an object definition, the @requiresScopes directive (including its scopes) will be applied to all field definitions defined on the object definition within that subgraph.
If the same object definition is defined in another subgraph without @requiresScopes, the corresponding field definitions unique to that that subgraph will be unaffected. But note that @requiresScopes could be applied to those field definitions through other means.
If at least one instance of a shared field is declared with @requiresScopes, that field definition will be declared with @requiresScopes in the federated graph (see Federation).
Consider the following example:
In subgraph-b, above, @requiresScopes has been declared on two object definitions:
The root object "Query"
The object "Object"
And those object definitions define the following field definitions:
Query.objectQuery
Query.objectsQuery
Object.intField
Object.stringField
Consequently, the @requiresScopes directive (including its defined scopes) would be applied to all field definitions at the paths listed above. The normalized graph would look like so:
When @requiresScopes is declared on an interface definition, the @requiresScopes directive (including its scopes) will be applied to all field definitions defined on the interface definition within that subgraph.
If the same interface definition is defined in another subgraph without @authenticated, the corresponding field definitions unique to that subgraph be unaffected. But note that @requiresScopes could be applied to those field definitions through other means.
In addition, @requiresScopes will be applied to the corresponding field definitions defined on the objects that implement that interfacewithin that subgraph.
If at least one instance of a shared field is declared with @requiresScopes, that field definition will be declared with @requiresScopes in the federated graph (see Federation).
Consider the following example:
In subgraph-c, above, @requiresScopes has been declared on the interface definition "Interface", which is implemented by two object definitions:
Object
AnotherObject
This interface defines the following field definitions:
Interface.intField
Interface.stringField
Consequently, the @requiresScopes directive (including its defined scopes) would be applied to all field definitions at the paths listed above, in addition to the same field definitions that are defined on the object definitions that implement that interface.
When @requiresScopes is declared on an interface field definition directly, the corresponding field definitions on the object types that implement that interface within that subgraph will also declare @requiresScopes (including its defined scopes). For example:
Sometimes, a field definition must combine multiple declarations of @requiresScopes.
Consider the following example:
# subgraph-e (raw)
type Query @requiresScopes(scopes: [["read:query"]]) {
enumField: Enum! @requiresScopes(scopes: [["read:private"]])
}
enum Enum @requiresScopes(scopes: [["read:enum"]]) {
VALUE
}
In this instance, the field definition Query.enumField is "inheriting" two other sets of scopes ("read:query" and "read:enum") in addition to its own set of scopes ("read:private").
These scopes are combined through the "AND" operator:
# subgraph-e (normalized)
type Query {
enumField: Enum! @requiresScopes(scopes: [
["read:private", "read:query", "read:enum"]
])
}
enum Enum {
VALUE
}
But sometimes, a field definition must combine more complicated declarations of @requiresScopes. These such cases are combined through matrix multiplication to ensure all contributed scopes are respected simultaneously.
In this instance, the field definition Query.enumField is once again "inheriting" two more declarations of @requiresScopes. But this time, there are multiple sets of OR and AND scopes, and each set of OR scopes is required by each other set of OR scopes.
Consequently, the "read:query" AND scope declared on Query must be added to both sets of OR scopes declared on Query.enumField. And the same again should happen with the "read:root" AND scope.
Finally, the scopes defined on Enum must also be applied. In this case, it's just a single AND scope ("read:enum"), so it can be applied without creating any new sets. In the event that Enum defined several OR scopes, a new set of scopes would be created for each.
The results are four new sets representing AND scopes, and each set of AND scopes represents an entire OR scope:
The @requiresScopes directive will persist in the federated schema. Consequently, if @requiresScopes is declared on a field definition in one graph, and the same field definition (a shared field) is defined in another graph without @requiresScopes, then @requiresScopes will still be declared on the federated field. This also means selecting this field will always require the relevant permissions, regardless of whether it would be resolved from a subgraph that did not declare @requiresScopes.
Consider the following two subgraphs and the resulting federated graph. The federated graph includes descriptions explaining how each @requiresScopes directive has persisted.
# federated graph
directive @requiresScopes(scopes: [[openfed__Scope!]!]!) on ENUM | FIELD_DEFINITION | INTERFACE | OBJECT | SCALAR
scalar openfed__Scope
type Query {
"Query.enumQuery @requiresScopes: read:enum from subgraph-g Enum"
enumQuery: Enum! @requiresScopes(scopes: [["read:enum"]])
interfacesQuery: [Interface!]!
"""
Scalar.enumQuery
@requiresScopes: read:scalar AND read:private from subgraph-h Scalar
"""
scalarQuery: Scalar @requiresScopes(scopes: [["read:scalar", "read:private"]])
}
"""
Scalar
@requiresScopes: (read:scalar AND read:private) initially added by subgraph-h Scalar
@requiresScopes applied to relevant field definitions and removed here
"""
scalar Scalar
"""
Enum @requiresScopes: read:enum initially added by subgraph-g Enum
@requiresScopes applied to relevant field definitions and removed here
"""
enum Enum {
VALUE
}
"""
Interface
@requiresScopes: ((read:interface AND read:object) OR (read:all))
initially added by subgraph-h Interface
@requiresScopes applied to relevant field definitions and removed here
"""
type Interface {
"""
Interface.booleanField @requiresScopes:
((read:interface AND read:object) OR (read:all)) from subgraph-h Interface
"""
booleanField: Boolean! @requiresScopes(scopes: [["read:interface", "read:object"],["read:all"]])
"""
Interface.enumField @requiresScopes:
((read:interface AND read:object) OR (read:all)) from subgraph-h Interface
"""
enumField: Enum! @requiresScopes(scopes: [["read:interface", "read:object"],["read:all"]])
intField: Int!
"""
Interface.stringField @requiresScopes:
((read:string) OR (read:scalar)) from subgraph-h Interface.stringField
"""
stringField: String! @requiresScopes(scopes: [["read:string"], ["read:scalar"]])
}
type Object implements Interface {
"""
Object.booleanField @requiresScopes:
((read:interface AND read:object) OR (read:all)) from subgraph-h Interface
"""
booleanField: @requiresScopes(scopes: [["read:interface", "read:object"],["read:all"]])
"""
Object.enumField @requiresScopes:
((read:interface AND read:object) OR (read:all)) from subgraph-h Interface
"""
enumField: Enum! @requiresScopes(scopes: [["read:interface", "read:object"],["read:all"]])
id: ID!
intField: Int!
objectOnlyBooleanField: Boolean!
"Object.objectOnlyEnumField @requiresScopes: read:enum from subgraph-g Enum"
objectOnlyEnumField: Enum! @requiresScopes(scopes: [["read:enum"]])
"""
Object.scalarField
@requiresScopes: (read:scalar AND read:private) from subgraph-h Scalar
"""
scalarField: Scalar! @requiresScopes(scopes: [["read:scalar", "read:private"]])
"""
Object.stringField @requiresScopes:
((read:string) OR (read:scalar)) from subgraph-h Interface.stringField
"""
stringField: String! @requiresScopes(scopes: [["read:string"], ["read:scalar"]])
}
"""
AnotherObject
@requiresScopes: "read:anotherobject" initially added by subgraph-f AnotherObject
@requiresScopes applied to relevant field definitions and removed here
"""
type AnotherObject implements Interface {
"""
AnotherObject.anotherObjectOnlyFloatField @requiresScopes:
read:anotherobject from subgraph-h AnotherObject
"""
anotherObjectOnlyFloatField: Float! @requiresScopes(scopes: [["read:anotherobject]])
"""
AnotherObject.anotherObjectOnlyScalarField @requiresScopes:
read:anotherobject from subgraph-h AnotherObject
(read:scalar AND read:private) from subgraph-h Scalar
"""
anotherObjectOnlyScalarField: Scalar! @requiresScopes(scopes: [["read:anotherobject", "read:scalar", "read:private"]])
"""
AnotherObject.booleanField @requiresScopes:
read:anotherobject from subgraph-h AnotherObject
((read:interface AND read:object) OR (read:all)) from subgraph-h Interface
"""
booleanField: @requiresScopes(scopes: [["read:anotherobject", "read:interface", "read:object"], ["read:anotherobject", "read:all"]])
"""
AnotherObject.enumField @requiresScopes:
read:anotherobject from subgraph-h AnotherObject
((read:interface AND read:object) OR (read:all)) from subgraph-h Interface
"""
enumField: Enum! @requiresScopes(scopes: [["read:anotherobject", "read:interface", "read:object"], ["read:anotherobject", "read:all"]])
"AnotherObject.id @requiresScopes: read:anotherobject from subgraph-h AnotherObject"
id: ID! @requiresScopes(scopes: [["read:anotherobject]])
"""
AnotherObject.intField
@requiresScopes: read:anotherobject from subgraph-h AnotherObject
"""
intField: Int! @requiresScopes(scopes: [["read:anotherobject]])
"""
AnotherObject.stringField @requiresScopes:
((read:string) OR (read:scalar)) from subgraph-g Interface.stringField
read:anotherobject from subgraph subgraph-h AnotherObject
"""
stringField: String! @requiresScopes(scopes: [["read:anotherobject", "read:string"], ["read:anotherobject", "read:scalar"]])
}
Errors
In the event that an agent without relevant permissions selects a non-nullable field that is declared with @requiresScopes, an authorization error will be returned, and the entire data will be null (see Non-nullable authenticated data requested among unauthenticated data).
{
"errors":[{
"message":"Unauthorized to load field 'Query.enumField'. Reason: required scopes: ('read:enum' AND 'read:field') OR ('read:all'), actual scopes: <none>",
"path":["enumField"]
}],
"data":null
}
In the event that an agent without relevant permissions selects a nullable field that is declared with @requiresScopes, an authorization error will be returned, and the specific field will be null (see Partial data):
{
"errors":[{
"message":"Unauthorized to load field 'Query.enumField'. Reason: required scopes: ('read:enum' AND 'read:field') OR ('read:all'), actual scopes: <none>",
"path":["enumField"]
}],
"data":{
"enumField":null
}
}
Partial data (nullable data requiring permissions)
Imagine an agent without relevant permissions selects a field that is declared with @requiresScopes and the response type of that field is nullable. However, the agent also selects a field that is not declared @requiresScopes (nor are any potential nested fields). In this event, an authorization error will still be returned, but the specific data that requires authentication will be null, while the data not requiring authentication will be returned.
Consider the following federated graph and corresponding query:
# federated graph
type Query {
"""Note that Query.intField is nullable"""
intField: Int @requiresScope(scopes: [["read:int"]])
"""Note that Query.floatField is non-nullable"""
floatField: Float! @authenticated(scopes: [["read:float"]])
stringField: String! # note that this field does not require any permissions
}
query {
intField
stringField
}
An agent without any permissions sending the query above would receive something like the following:
{
"errors":[{
"message":"Unauthorized to load field 'Query.intField'. Reason: required scopes: 'read:int', actual scopes: <none>",
"path":["intField"]
}],
"data":{
"intField":null,
"stringField":"I'm a string!"
}
}
Non-nullable authenticated data requested among unauthenticated data
In the event an agent without relevant permissions selects any non-nullable fields that declare @requiresScopes and therefore require one or more permissions, an authorization error will be returned, and the entire data will return null. This is true even if one or more field selections did not require permissions or are nullable.
Consider the following federated graph and corresponding query:
# federated graph
type Query {
objectField: Object!
stringField: String!
}
type Object {
uauthenticatedObjectField: String!
unauthenticatedNestedObject: NestedObject!
}
type NestedObject {
"""Note that NestedObject.authenticatedIntField is non-nullable"""
authenticatedIntField: Int! @requiresScopes(scopes: [["read:int"]])
unauthenticatedStringField: String!
}
query {
stringField
objectField {
unauthenticatedObjectField
unauthenticatedNestedObjectField {
authenticatedNonNullableIntField # only this field requires permissions
unauthenticatedStringField
}
}
}
An agent without the "read:int" permission sending the query above would receive something like the following:
{
"errors":[{
"message":"Unauthorized to load field 'Query.objectField.unauthenticatedNestedObjectField.authenticatedNonNullableIntField'. Reason: required scopes: 'read:int', actual scopes: <none>",
"path":["objectField","unauthenticatedNestedObectField","authenticatedNonNullableIntField"]
}],
"data":null
}
Partial permissions
An agent must have all relevant permissions within at least one entire set of AND scopes among the OR scopes declared through @requiresScopes for a selected field to return data. In the event that the agent has some but not all permissions, the error message will be transparent:
{
"errors":[{
"message":"Unauthorized to load field 'Query.employeeField'. Reason: required scopes: ('read:employee' AND 'read:private') OR ('read:all'), actual scopes: read:employee",
"path":["employeeField"]
}],
"data":null
}
.svg?alt=media&token=06f1bc51-8b97-4fc6-8caf-fdd3a8cd9ec8)