changes to the authentication page

Author: rsill-neo4j

modules/ROOT/pages/security/authentication.adoc

@@ -1,13 +1,62 @@
 = Authentication
 :description: This page describes how to set up authentication features in the Neo4j GraphQL Library.
 
-Explicit authentication, configured using the `@authentication` directive, is only ever evaluated 
-during Cypher translation time, and unauthenticated requests with queries requiring authentication 
-will never reach the database.
+The GraphQL Library offers the `@authentication` directive to configure authentication for certain operations and for different parts of your schema.
 
-== Configuration
+[NOTE]
+Explicit authentication, configured with the `@authentication` directive, is only ever evaluated during Cypher translation time, and unauthenticated requests with queries requiring authentication never reach the database.
 
-Authentication can be configured for an entire type, for example, the type `User`:
+== Operations
+
+Authentication can be configured to only be validated on certain operations:
+
+* `CREATE`
+* `READ`
+* `AGGREGATE`
+* `UPDATE`
+* `DELETE`
+* `CREATE_RELATIONSHIP`
+* `DELETE_RELATIONSHIP`
+* `SUBSCRIBE`
+
+
+For instance, to only require authentication for the update or deletion of a user:
+
+[source, graphql, indent=0]
+----
+type User @authentication(operations: [UPDATE, DELETE]) {
+    id: ID!
+    name: String!
+    password: String!
+}
+----
+
+[NOTE]
+If there is no `operations` argument with a list of operations, the GraphQL Library treats the authentication configuration as if the full list of operations had been provided.
+
+
+== Scope
+
+
+=== Global authentication
+
+Athentication can be applied to the entire schema.
+This ensures authentication is checked for every matching request.
+
+Extend the schema:
+
+[source, graphql, indent=0]
+----
+extend schema @authentication
+----
+
+The `operations` and `jwt` arguments can also be used when the directive is applied to a schema extension.
+
+// ^ should we add links or provide examples? 
+
+=== Authentication for types
+
+Authentication can be configured for an entire type:
 
 [source, graphql, indent=0]
 ----
@@ -18,7 +67,7 @@ type User @authentication {
 }
 ----
 
-Authentication will thus be validated when any of the following operations are _attempted_:
+With this configuration, authentication is validated when any of the following operations are _attempted_:
 
 * *Create*: `createUsers` mutation, `create`, or `connectOrCreate` nested operation via a related type.
 * *Read*: `users`, `usersConnection`, `usersAggregate` query, or access via related type.
@@ -28,7 +77,10 @@ Authentication will thus be validated when any of the following operations are _
 * *Delete relationship*: `disconnect` nested operation via a related type.
 * *Subscribe*: all subscription operations related to type `User`.
 
-Additionally, the directive can be configured on a per-field basis, for example:
+
+=== Authentication for fields
+
+Authentication can be configured on a per-field basis, for example:
 
 [source, graphql, indent=0]
 ----
@@ -39,37 +91,13 @@ type User {
 }
 ----
 
-This will only be evaluated in the following circumstances:
+This is only evaluated under the following circumstances:
 
 * The `password` field is set on either `create` or `update`.
 * The `password` field is present in a selection set.
 
-=== Operations
-
-Authentication can be configured to only be validated on certain operations:
-
-* `CREATE`
-* `READ`
-* `AGGREGATE`
-* `UPDATE`
-* `DELETE`
-* `CREATE_RELATIONSHIP`
-* `DELETE_RELATIONSHIP`
-* `SUBSCRIBE`
-
 
-For instance, to only require authentication for the update or deletion of a user:
-
-[source, graphql, indent=0]
-----
-type User @authentication(operations: [UPDATE, DELETE]) {
-    id: ID!
-    name: String!
-    password: String!
-}
-----
-
-=== Additional verification
+== Additional verification
 
 Additional checks against JWT claims can be performed together with authentication. 
 For instance, if it was a requirement that only users with the `admin` role can delete users:
@@ -81,18 +109,4 @@ type User @authentication(operations: [DELETE], jwt: { roles_INCLUDES: "admin" }
     name: String!
     password: String!
 }
-----
-
-== Global authentication
-
-Additionally, authentication can be applied to the entire schema.
-This ensures authentication is checked for every matching request.
-
-This is done via extending the schema:
-
-[source, graphql, indent=0]
-----
-extend schema @authentication
-----
-
-The `operations` and `jwt` arguments can also be used when the directive is applied to a schema extension.
+----