Apply suggestions from code review

Co-authored-by: Lidia Zuin <[email protected]>

Author: rsill-neo4j

modules/ROOT/pages/security/authentication.adoc

@@ -3,8 +3,11 @@
 
 The GraphQL Library offers the `@authentication` directive to configure authentication for certain operations and for different parts of your schema.
 
-[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.
+[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.
+====
 
 == Operations
 
@@ -19,7 +22,6 @@ Authentication can be configured to only be validated on certain operations:
 * `DELETE_RELATIONSHIP`
 * `SUBSCRIBE`
 
-
 For instance, to only require authentication for the update or deletion of a user:
 
 [source, graphql, indent=0]
@@ -32,15 +34,15 @@ type User @authentication(operations: [UPDATE, DELETE]) {
 ----
 
 [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.
-
+====
+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
 
-Athentication can be applied to the entire schema.
+Authentication can be applied to the entire schema.
 This ensures authentication is checked for every matching request.
 
 Extend the schema:

modules/ROOT/pages/security/authorization.adoc

@@ -67,7 +67,9 @@ type Post @authorization(filter: [
 ----
 
 [NOTE]
-If 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.
+====
+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
@@ -119,7 +121,9 @@ type Post @authorization(validate: [
 ----
 
 [NOTE]
-If 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.
+====
+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

modules/ROOT/pages/security/configuration.adoc

@@ -5,7 +5,7 @@ The Neo4j GraphQL Library uses JSON Web Token (JWT) authentication.
 JWTs are tokens containing claims or statements about the user or client making the request.
 These claims can include information such as the user's ID or roles.
 
-A JWT can be obtained from an authentication service and is then included in an API request.
+A JWT can be obtained from an authentication service and then be included in an API request.
 The API verifies the JWT and returns the requested data if the JWT is valid.
 
 == Instantiation
@@ -17,8 +17,9 @@ The Neo4j GraphQL Library can accept two types of JWTs:
 
 === Encoded JWTs
 
-To use encoded JWTs, the library can be configured with a key to decode and verify the tokens.
-The following code block uses Apollo Server, extracts the `Authorization` header from the request and puts it in the appropriate context field:
+In order to use encoded JWTs, configure the library with a key to decode and verify the tokens.
+The following code block uses Apollo Server. 
+It extracts the `Authorization` header from the request and puts it in the appropriate context field:
 
 [source, typescript, indent=0]
 ----
@@ -115,8 +116,9 @@ interface JwtPayload {
 ----
 
 [WARNING]
+====
 Do not pass in the header or the signature.
-
+====
 
 === Decoded JWTs
 
@@ -136,8 +138,7 @@ const { url } = await startStandaloneServer(server, {
 ----
 
 `customImplementation` is a placeholder for a function that provides a decoded JWT.
-Using `jwt` instead of `token` in the `context` informs the Neo4jGraphQL library that it doesn't need to decode it.
-
+Using `jwt` instead of `token` in the `context` informs the Neo4j GraphQL Library that it doesn't need to decode it.
 
 == Adding JWT claims
 
@@ -157,12 +158,15 @@ type JWT @jwt {
 ----
 
 [NOTE]
-Note that the type name `JWT` is not required.
+====
+The type name `JWT` is not mandatory.
 You can use any name as long as it is decorated with the `@jwt` directive.
+====
 
 === The `@jwtClaim` directive
 
-A `roles` claim is not necessarily located at the JWT payload root, but can instead be in a nested location, for example under `myApplication`:
+A `roles` claim is not necessarily located at the JWT payload root.
+It can instead be in a nested location, for example under `myApplication`:
 
 [source, json, indent=0]
 ----
@@ -195,7 +199,7 @@ Additionally, the nested location may contain `.` characters in the path, for ex
 }
 ----
 
-Escape these characters:
+These characters must be escaped:
 
 [source, graphql, indent=0]
 ----

modules/ROOT/pages/security/operations.adoc

@@ -4,7 +4,7 @@
 
 This page showcases a number of GraphQL queries and how you can trigger the evaluation of different authentication and authorization rules.
 
-Each relevant line has a comment such as `CREATE ON OBJECT Movie`, which means an authentication directive like the following is be evaluated:
+Each relevant line has a comment such as `CREATE ON OBJECT Movie`, which means an authentication directive like the following is evaluated:
 
 [source, graphql, indent=0]
 ----
@@ -14,8 +14,10 @@ type Movie @authentication(operations: [CREATE]) {
 }
 ----
 
-[NOTE]
+[IMPORTANT]
+====
 This also applies if the directive has no arguments because `operations` defaults to _all_ operations.
+====
 
 The following examples apply to the `@authentication` directive, and also any rules within an `@authorization` directive.