Updates for the security section

modules/ROOT/pages/directives/index.adoc

@@ -40,10 +40,10 @@ a| Required to differentiate interfaces that are used for relationship propertie
 | xref::/security/authorization.adoc[`@authorization`]
 | Specifies authorization rules for queries and mutations on the type.
 
-| xref::/security/configuration.adoc#authentication-and-authorization-jwt[`@jwt`]
+| xref::/security/configuration.adoc#_the_jwt_directive[`@jwt`]
 | Configures the JWT authentication and authorization filters to include additional JWT claims.
 
-| xref::/security/configuration.adoc#_nested_claims[`@jwtClaim`]
+| xref::/security/configuration.adoc#_the_jwtclaim_directive[`@jwtClaim`]
 | Used in combination with `@jwt`.
 Configures the JWT authentication and authorization filters to include an additional JWT claim which is either nested or using special characters not supported by GraphQL.
 

modules/ROOT/pages/security/authentication.adoc

@@ -1,13 +1,64 @@
 = 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
+[IMPORTANT]
+====
+Explicit authentication, configured with the `@authentication` directive, is only ever evaluated during Cypher translation time.
+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]
+====
+In case 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
+
+Authentication 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 +69,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 +79,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 +93,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 +111,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.
+----

modules/ROOT/pages/security/authorization.adoc

@@ -66,6 +66,11 @@ type Post @authorization(filter: [
 }
 ----
 
+[NOTE]
+====
+In case there is no `operations` argument with a list of operations, the GraphQL Library treats the authorization configuration as if the full list of operations had been provided.
+====
+
 
 === Validating
 
@@ -115,6 +120,11 @@ type Post @authorization(validate: [
 }
 ----
 
+[NOTE]
+====
+In case there is no `operations` argument with a list of operations, the GraphQL Library treats the authorization configuration as if the full list of operations had been provided.
+====
+
 
 == Authorization without authentication