GraphOS Authorization

[Geal]

This is the public discussion for the new GraphOS Authorization feature, currently in preview

[oyasnev]

Hi Geal(@Geal), I'm evaluating the new authorization feature, and that looks great!

Do you know how I could expose the info about the required scopes to API consumers? The requiresScopes directive is a part of my supergraph schema and works on the router level, however in the Schema Explorer the directive is not shown (opposite to e.g. deprecated directive).
Is it because the feature is in preview, or do you have some plans to make the scope requirements visible?

Thanks!

Best,
Oleg

[Geal]

If you're using the Explorer instance directly provided by the router, it gets the schema using introspection, and unfortunately, introspection does not return directive application (not specifically in the router, it's at the spec level: https://github.com/graphql/graphql-spec/blob/main/spec/Section%204%20--%20Introspection.md). You could get the SDL from Studio and export that to your customers though

[oyasnev]

Thanks for the prompt reply! Yes, I'm using the Explorer instance provided by the router as making a local prototype so far.
Did I get you right that once deployed to Apollo Studio the scopes will be exposed there (in Schema Reference, Explorer or somewhere else)? Our consumers are internal teams which will have access to the Studio with Observer roles.

Just out of curiosity, are directives like deprecated processed by the introspection differently? 'Cause the deprecated directive made it to the local router Explorer.
From the Schema Type:

directives must return the set of all directives available within this schema including all built-in directives.

and Directive Type

This includes both any built-in directive and any custom directive.

That's why I expected requiresScopes to be displayed in the Explorer since it was included into the composed supergraph schema. But it's not returned when quering for the schema:

{
  __schema {
    directives {
      name
    }
  }
}

[Geal]

@deprecated has special handling. In the link, if you look at what is returned for fields:

type __Field {
  name: String!
  description: String
  args(includeDeprecated: Boolean = false): [__InputValue!]!
  type: __Type!
  isDeprecated: Boolean!
  deprecationReason: String
}

The isDeprecated and deprecationReason fields are used to reconstruct the directive application.

directives must return the set of all directives available within this schema including all built-in directives.

this means that the directive definition should appear, ie this:

directive @requiresScopes(scopes: [[federation__Scope!]!]!) on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM

but not the applications. Are you saying that even the definition is not returned by introspection?

[oyasnev]

Hi Geal, yes, from what I can see nothing regarding the requiredScopes directive is returned.

Let me show you the minimal example with one service to reproduce the issue:

schema.graphql:

extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@requiresScopes"])

type Query {
    orders: [Order!]! @requiresScopes(scopes: [["read:order"]])
}

type Order @key(fields: "id"){
    id: ID!
}

supergraph.yml:

federation_version: =2.5.0
subgraphs:
  orders:
    routing_url: http://localhost:4002/
    schema:
      file: ./orders/schema.graphql

router config.yml:

authorization:
  preview_directives:
    enabled: true

I compose the supergraph schema with the following command:
rover supergraph compose --output ./supergraph-schema.graphql --config ./supergraph.yml

the composed supergraph-schema.graphql:

schema
  @link(url: "https://specs.apollo.dev/link/v1.0")
  @link(url: "https://specs.apollo.dev/join/v0.3", for: EXECUTION)
  @link(url: "https://specs.apollo.dev/requiresScopes/v0.1", for: SECURITY)
{
  query: Query
}

directive @join__enumValue(graph: join__Graph!) repeatable on ENUM_VALUE

directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION

directive @join__graph(name: String!, url: String!) on ENUM_VALUE

directive @join__implements(graph: join__Graph!, interface: String!) repeatable on OBJECT | INTERFACE

directive @join__type(graph: join__Graph!, key: join__FieldSet, extension: Boolean! = false, resolvable: Boolean! = true, isInterfaceObject: Boolean! = false) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR

directive @join__unionMember(graph: join__Graph!, member: String!) repeatable on UNION

directive @link(url: String, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA

directive @requiresScopes(scopes: [requiresScopes__Scope!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM

scalar join__FieldSet

enum join__Graph {
  ORDERS @join__graph(name: "orders", url: "http://localhost:4002/")
}

scalar link__Import

enum link__Purpose {
  """
  `SECURITY` features provide metadata necessary to securely resolve fields.
  """
  SECURITY

  """
  `EXECUTION` features provide metadata necessary for operation execution.
  """
  EXECUTION
}

type Order
  @join__type(graph: ORDERS, key: "id")
{
  id: ID!
}

type Query
  @join__type(graph: ORDERS)
{
  orders: [Order!]! @requiresScopes(scopes: [["read:order"]])
}

scalar requiresScopes__Scope

Finally, I start the router in a dev mode:
./router --dev --config config.yml --supergraph ../supergraph-schema.graphql

Now open http://localhost:4000/.

Schema tab:

• Reference -> Directives: @defer, @deprecated, @include, @Skip, @SpecifiedBy
• SDL:

  directive @defer(label: String, if: Boolean! = true) on FRAGMENT_SPREAD | INLINE_FRAGMENT
  
  type Order {
    id: ID!
  }
  
  type Query {
    orders: [Order!]!
  }

I would expect to see in SDL @requiresScopes(scopes: [["read:order"]]) next to orders field to be aware of which field requires which authorization.

Explorer tab. Run

{
  __schema {
    directives {
      name
    }
  }
}

Response:

{
  "data": {
    "__schema": {
      "directives": [
        {
          "name": "defer"
        },
        {
          "name": "include"
        },
        {
          "name": "skip"
        },
        {
          "name": "deprecated"
        },
        {
          "name": "specifiedBy"
        }
      ]
    }
  }
}

I would expect to see requiredScopes among other directives since it's effectively part of the supergraph schema and processed by the router as expected (i.e. blocking unauthotrized requests).