Merge pull request rmosolgo#1494 from rmosolgo/integrated-auth

Integrated Authorization

Author: Robert Mosolgo

guides/authorization/accessibility.md

@@ -0,0 +1,63 @@
+---
+layout: guide
+search: true
+section: Authorization
+title: Accessibility
+desc: Reject queries from unauthorized users if they access certain parts of the schema.
+index: 2
+---
+
+With GraphQL-Ruby, you can inspect an incoming query, and return a custom error if that query accesses some unauthorized parts of the schema.
+
+This is different from {% internal_link "visibility", "/authorization/visibility" %}, where unauthorized parts of the schema are treated as non-existent. It's also different from {% internal_link "authorization", "/authorization/authorization" %}, which makes checks _while running_, instead of _before running_.
+
+## Preventing Access
+
+You can override some `.accessible?(context)` methods to prevent access to certain members of the schema:
+
+- Type and mutation classes have a `.accessible?(context)` class method
+- Arguments and fields have a `.accessible?(context)` instance method
+
+These methods are called with the query context, based on the hash you pass as `context:`.
+
+Whenever that method is implemented to return `false`, the currently-checked field will be collected as inaccessible. For example:
+
+```ruby
+class BaseField < GraphQL::Schema::Field
+  def initialize(preview:, **kwargs, &block)
+    @preview = preview
+    super(**kwargs, &block)
+  end
+
+  # If this field was marked as preview, hide it unless the current viewer can see previews.
+  def accessible?(context)
+    if @preview && !context[:viewer].can_preview?
+      false
+    else
+      super
+    end
+  end
+end
+```
+
+Now, any fields created with `field(..., preview: true)` will be _visible_ to everyone, but only accessible to users where `.can_preview?` is `true`.
+
+## Adding an Error
+
+By default, GraphQL-Ruby will return a simple error to the client if any `.accessible?` checks return false.
+
+You can customize this behavior by overriding {{ "Schema.inaccessible_fields" | api_docs }}, for example:
+
+```ruby
+class MySchema < GraphQL::Schema
+  # If you have a custom `permission_level` setting on your `GraphQL::Field` class,
+  # you can access it here:
+  def self.inaccessible_fields(error)
+    required_permissions = error.fields.map(&:permission_level).uniq
+    # Return a custom error
+    GraphQL::AnalysisError.new("You need certain permissions: #{required_permissions.join(", ")}")
+  end
+end
+```
+
+Then, your custom error will be added to the response instead of the default one.

guides/authorization/authorization.md

@@ -0,0 +1,56 @@
+---
+layout: guide
+search: true
+section: Authorization
+title: Authorization
+desc: During execution, check if the current user has permission to access retrieved objects.
+index: 3
+---
+
+While a query is running, you can check each object to see whether the current user is authorized to interact with that object. If the user is _not_ authorized, you can handle the case with an error.
+
+## Adding Authorization Checks
+
+Schema members have `.authorized?(value, context)` methods which will be called during execution:
+
+- Type and mutation classes have `.authorized?(value, context)` class methods
+- Fields and arguments have `#authorized?(value, context)` instance methods
+
+These methods are called with:
+
+- `value`: the object from your application which was returned from a field
+- `context`: the query context, based on the hash passed as `context:`
+
+When you implement this method to return `false`, the query will be halted, for example:
+
+```ruby
+class Types::Friendship < Types::BaseObject
+  # You can only see the details on a `Friendship`
+  # if you're one of the people involved in it.
+  def self.authorized?(object, context)
+    super && (object.to_friend == context[:viewer] || object.from_friend == context[:viewer])
+  end
+end
+```
+
+(Always call `super` to get the default checks, too.)
+
+Now, whenever an object of type `Friendship` is going to be returned to the client, it will first go through the `.authorized?` method. If that method returns false, the field will get `nil` instead of the original object, and you may handle that case with an error (see below).
+
+## Handling Unauthorized Objects
+
+By default, GraphQL-Ruby silently replaces unauthorized objects with `nil`, as if they didn't exist. You can customize this behavior by implementing {{ "Schema.unauthorized_object" | api_doc }} in your schema class, for example:
+
+```ruby
+class MySchema < GraphQL::Schema
+  # Override this hook to handle cases when `authorized?` returns false:
+  def self.unauthorized_object(error)
+    # Increment a metric somewhere:
+    AppStats.increment("graphql:unauthorized:#{error.type.graphql_name}:#{error.object.class.name}")
+    # Add a top-level error to the response instead of returning nil:
+    raise GraphQL::ExecutionError, "An object of type #{error.type.graphql_name} was hidden due to permissions"
+  end
+end
+```
+
+Now, the custom hook will be called instead of the default one.

guides/authorization/overview.md

@@ -0,0 +1,138 @@
+---
+layout: guide
+search: true
+section: Authorization
+title: Overview
+desc: Overview of GraphQL authorization in general and an intro to the built-in framework.
+index: 0
+---
+
+Here's a conceptual approach to GraphQL authorization, followed by an introduction to the built-in authorization framework. Each part of the framework is described in detail in its own guide.
+
+## Authorization: GraphQL vs REST
+
+In a REST API, the common authorization pattern is fairly simple. Before performing the requested action, the server asserts that the current client has the required permissions for that action. For example:
+
+```ruby
+class PostsController < ApiController
+  def create
+    # First, check the client's permission level:
+    if current_user.can?(:create_posts)
+      # If the user is permitted, then perform the action:
+      post = Post.create(params)
+      render json: post
+    else
+      # Otherwise, return an error:
+      render nothing: true, status: 403
+    end
+  end
+end
+```
+
+However, this request-by-request mindset doesn't map well to GraphQL because there's only one controller and the requests that come to it may be _very_ different. To illustrate the problem:
+
+```ruby
+class GraphqlController < ApplicationController
+  def execute
+    # What permission is required for `query_str`?
+    # It depends on the string! So, you can't generalize at this level.
+    if current_user.can?(:"???")
+      MySchema.execute(query_str, context: ctx, variables: variables)
+    end
+  end
+end
+```
+
+So, what new mindset will work with a GraphQL API?
+
+For __mutations__, remember that each mutation is like an API request in itself. For example, `Posts#create` above would map to the `createPost(...)` mutation in GraphQL. So, each mutation should be authorized in its own right.
+
+For __queries__, you can think of each individual _object_ like a `GET` request to a REST API. So, each object should be authorized for reading in its own right.
+
+By applying this mindset, each part of the GraphQL query will be properly authorized before it is executed. Also, since the different units of code are each authorized on their own, you can be sure that each incoming query will be properly authorized, even if it's a brand new query that the server has never seen before.
+
+## What About Authentication?
+
+As a reminder:
+
+- _Authentication_ is the process of determining what user is making the current request, for example, accepting a username and password, or finding a `User` in the database from `session[:current_user_id]`.
+- _Authorization_ is the process of verifying that the current user has permission to do something (or see something), for example, checking `admin?` status or looking up permission groups from the database.
+
+In general, authentication is _not_ addressed in GraphQL at all. Instead, your controller should get the current user based on the HTTP request (eg, an HTTP header or a cookie) and provide that information to the GraphQL query. For example:
+
+```ruby
+class GraphqlController < ApplicationController
+  def execute
+    # Somehow get the the current `User` from this HTTP request.
+    current_user = get_logged_in_user(request)
+    # Provide the current user in `context` for use during the query
+    context = { current_user: current_user }
+    MySchema.execute(query_str, context: context, ...)
+  end
+end
+```
+
+After your HTTP handler has loaded the current user, you can access it via `context[:current_user]` in your GraphQL code.
+
+## Authorization in Your Business Logic
+
+Before introducing GraphQL-specific authorization, consider the advantages of application-level authorization. (See the [GraphQL.org post](https://graphql.org/learn/authorization/) on the same topic.) For example, here's authorization mixed into the GraphQL API layer:
+
+```ruby
+field :posts, [Types::Post], null: false
+
+def posts
+  # Perform an auth check in the GraphQL field code:
+  if context[:current_user].admin?
+    Post.all
+  else
+    Post.published
+  end
+end
+```
+
+The downside of this is that, when `Types::Post` is queried in other contexts, the same authorization check may not be applied. Additionally, since the authorization code is coupled with the GraphQL API, the only way to test it is via GraphQL queries, which adds some complexity to tests.
+
+Alternatively, you could move the authorization to your business logic, the `Post` class:
+
+```ruby
+class Post < ActiveRecord::Base
+  # Return the list of posts which `user` may see
+  def self.posts_for(user)
+    if user.admin?
+      self.all
+    else
+      self.published
+    end
+  end
+end
+```
+
+Then, use this application method in your GraphQL code:
+
+```ruby
+field :posts, [Types::Post], null: false
+
+def posts
+  # Fetch the posts this user can see:
+  Post.posts_for(context[:current_user])
+end
+```
+
+In this case, `Post.posts_for(user)` could be tested _independently_ from GraphQL. Then, you have less to worry about in your GraphQL tests. As a bonus, you can use `Post.posts_for(user)` in _other_ parts of the app, too, such as the web UI or REST API.
+
+## GraphQL-Ruby's Authorization Framework
+
+Despite the advantages of authorization at the application layer, as described above, there might be some reasons to authorize in the API layer:
+
+- Have an extra assurance that your API layer is secure
+- Authorize the API request _before_ running it (see "visibility" below)
+- Integrate with code that doesn't have authorization built-in
+
+To accomplish these, you can use GraphQL-Ruby's authorization framework. The framework has three levels, each of which is described in its own guide:
+
+- {% internal_link "Visibility", "/authorization/visibility" %} hides parts of the GraphQL schema from users who don't have full permission.
+- {% internal_link "Accessibility", "/authorization/accessibility" %} prevents running queries which access parts of the GraphQL schema, unless users have the required permission.
+- {% internal_link "Authorization", "/authorization/authorization" %} checks application objects during execution to be sure the user has permission to access them.
+
+Also, GraphQL::Pro has integrations for CanCan and Pundit.

guides/authorization/visibility.md

@@ -0,0 +1,56 @@
+---
+layout: guide
+search: true
+section: Authorization
+title: Visibility
+desc: Programatically hide parts of the GraphQL schema from some users.
+index: 1
+---
+
+With GraphQL-Ruby, it's possible to _hide_ parts of your schema from some users. This isn't exactly part of the GraphQL spec, but it's roughly within the bounds of the spec.
+
+Here are some reasons you might want to hide parts of your schema:
+
+- You don't want non-admin users to know about administration functions of the schema.
+- You're developing a new feature and want to make a gradual release to only a few users first.
+
+## Hiding Parts of the Schema
+
+You can customize the visibility of parts of your schema by reimplementing various `visible?` methods:
+
+- Type classes have a `.visible?(context)` class method
+- Fields and arguments have a `#visible?(context)` instance method
+- Enum values have `#visible?(context)` instance method
+- Mutation classes have a `.visible?(context)` class method
+
+These methods are called with the query context, based on the hash you pass as `context:`. If the method returns false, then that member of the schema will be treated as though it doesn't exist for the entirety of the query. That is:
+
+- In introspection, the member will _not_ be included in the result
+- In normal queries, if a query references that member, it will return a validation error, since that member doesn't exist
+
+## For Example
+
+Let's say you're working on a new feature which should remain secret for a while. You can implement `.visible?` in a type:
+
+```ruby
+class Types::SecretFeature < Types::BaseObject
+  def self.visible?(context)
+    # only show it to users with the secret_feature enabled
+    super && context[:viewer].feature_enabled?(:secret_feature)
+  end
+end
+```
+
+(Always call `super` to inherit the default behavior.)
+
+Now, the following bits of GraphQL will return validation errors:
+
+- Fields that return `SecretFeature`, eg `query { findSecretFeature { ... } }`
+- Fragments on `SecretFeature`, eg `Fragment SF on SecretFeature`
+
+And in introspection:
+
+- `__schema { types { ... } }` will not include `SecretFeature`
+- `__type(name: "SecretFeature")` will return `nil`
+- Any interfaces or unions which normally include `SecretFeature` will _not_ include it
+- Any fields that return `SecretFeature` will be excluded from introspection

guides/guides.html

@@ -5,6 +5,7 @@
   - name: Queries
   - name: Types
   - name: Type Definitions
+  - name: Authorization
   - name: Fields
   - name: Mutations
   - name: Errors

lib/graphql.rb

@@ -99,3 +99,5 @@ def self.scan_with_ragel(graphql_string)
 require "graphql/backtrace"
 
 require "graphql/deprecated_dsl"
+require "graphql/authorization"
+require "graphql/unauthorized_error"

lib/graphql/argument.rb

@@ -38,6 +38,7 @@ class Argument
     accepts_definitions :name, :type, :description, :default_value, :as, :prepare
     attr_accessor :type, :description, :default_value, :name, :as
     attr_accessor :ast_node
+    alias :graphql_name :name
 
     ensure_defined(:name, :description, :default_value, :type=, :type, :as, :expose_as, :prepare)