Apply suggestions from code review

authentication providers section

Author: rsill-neo4j

modules/ROOT/pages/aura-graphql-data-apis/authentication-providers.adoc

@@ -1,27 +1,41 @@
 [[auth-providers]]
-= Authentication Providers
+= Authentication providers
 
-GraphQL for Neo4j AuraDB allows you to use an API key, JWT token from an external identity provider or both for authentication and switch between them as needed. The authentication method is stored as an authentication provider.
+GraphQL for Neo4j AuraDB allows you to use an API key, JWT token from an external identity provider or both for authentication and switch between them as needed.
+The authentication method is stored as an authentication provider.
 
-There are advantages and disadvantages of both types. API keys are quick to start working with but do not allow for access controls and should not be used within a user facing-client application. JWKS (JSON Web Key Sets) authentication providers require an external identity provider but do allow for fine grained rules around authentication/authorization.
+There are advantages and disadvantages to both types.
+API keys are quickly set up but do not allow for access control and should not be used within a user-facing client application.
+JWKS (JSON Web Key Sets) authentication providers require an external identity provider but do allow for fine-grained rules around authentication/authorization.
 
 [NOTE]
 ====
-`--data-api-id` is used with the `aura-cli` when working with authentication providers rather than `--graphql-api-id` as you might have expected. Conceptually a GraphQL API is a type of Data API and there may be other types in the future. Using `--data-api-id` allows for flexibility for potential future development work in this area.
+`--data-api-id` is used with the `aura-cli` when working with authentication providers rather than `--graphql-api-id` as you might have expected.
+Conceptually a GraphQL API is a type of data API and there may be other types in the future.
+Using `--data-api-id` allows for flexibility for potential future development work in this area.
 ====
 
-== Create a JWKS Authentication Provider
+== Creating a JWKS authentication provider
 
-Before using JWKS authentication providers, it is necessary to set up and configure an identity provider that manages users and their credentials securely, issues JWTs to authenticated users, and hosts a JWKS endpoint that is can be used to validate JWTs by the GraphQL API. There are several 3rd parties who provide this type of service, e.g Ping, Okta, Auth0 and any of the main cloud service providers. Configuration of identity providers is beyond the scope of this guide.
+Before using JWKS authentication providers, you must set up and configure an identity provider that:
 
-If you do use a JWKS authentication provider, then you can take advantage of fine-grained access controls using the ** xref:security/authentication.adoc[`@authentication`]/** xref:security/authorization.adoc[`@authorization`] directives of Graphql for Neo4j AuraDB.
+ * manages users and their credentials securely,
+ * issues JWTs to authenticated users
+ * hosts a JWKS endpoint that can be used to validate JWTs by the GraphQL API.
+ 
+ There are several 3rd parties who provide this type of service, e.g. Ping, Okta, Auth0 and any of the main cloud service providers.
+ Configuration of identity providers is beyond the scope of this guide.
+
+If you do use a JWKS authentication provider, you can take advantage of fine-grained access controls using the xref:security/authentication.adoc[`@authentication`] and xref:security/authorization.adoc[`@authorization`] directives of GraphQL for Neo4j AuraDB.
 
 [NOTE]
 ====
-If you do make use of `@authentication`/`@authorization` rules, they will also be applied to requests made with API keys. We do not currently support adding claims to API keys so it is unlikely they will be able to meet the rules you specify.
+If you make use of `@authentication` or `@authorization` rules, they are also applied to requests made with API keys.
+We do not currently support adding claims to API keys so it is unlikely they are able to meet the rules you specify.
 ====
 
-The aura-cli is used to create a new JWKS authentication provider. You will need the JWKS URL to do this along with the ID of the GraphQL API with it’s associated AuraDB ID.
+The aura-cli is used to create a new JWKS authentication provider.
+You will need the JWKS URL to do this along with the ID of the GraphQL API with its associated AuraDB ID.
 
 At a command prompt, type the following, swapping out the UPPERCASE values for your own:
 
@@ -30,16 +44,19 @@ At a command prompt, type the following, swapping out the UPPERCASE values for y
 aura-cli data-api graphql auth-provider create --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --name AUTH_PROVIDER_FRIENDLY_NAME --type jwks --url JWKS_URL
 ----
 
-On success, the command will respond with details about the newly created JWKS provider.
+On success, the command responds with details about the newly created JWKS provider.
 
-== Create an API Key Authentication Provider
+== Creating an API Key Authentication Provider
 
 [WARNING]
 ====
-If you use an API key authentication provider in a user-facing client application, you risk leaking the API key to your users. This could potential give them full access to your GraphQL API. For these usecases, we recommend using JWKS authentication providers.
+If you use an API key authentication provider in a user-facing client application, you risk leaking the API key to your users.
+This can give them full access to your GraphQL API.
+We recommend you to use JWKS authentication providers in user-facing client applications.
 ====
 
-When a new GraphQL API is created via the aura-cli, an API Key authentication provider is the default. However, if you require a new one, this command allows you to create a new API Key.
+When a new GraphQL API is created via the aura-cli, an API key authentication provider is the default.
+However, if you require a new one, the following command allows you to create a new API Key.
 
 At a command prompt, type the following, swapping out the UPPERCASE values for your own:
 
@@ -55,7 +72,7 @@ On success, the command will respond with details about the newly created API Ke
 Make sure to record the API key shown in the response as it will not be displayed again.
 ====
 
-== List Authentication Providers
+== Listing authentication providers
 
 To see the list of authentication providers for a given GraphQL API use the following, exchanging UPPERCASE values for your own.
 
@@ -64,19 +81,20 @@ To see the list of authentication providers for a given GraphQL API use the foll
 aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID
 ----
 
-== Delete an Authentication Provider
+== Deleting an authentication provider
 
-An authentication provider for a GraphQL API can be removed by deleting it. At least one enabled authentication provider is required for a GraphQL API.
+An authentication provider for a GraphQL API can be removed by deleting it.
+At least one enabled authentication provider is required for a GraphQL API.
 
-. Find the API authentication provider ID
+. Find the API authentication provider ID.
 +
 [source, bash, indent=0]
 ----
 aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --output table
 ----
 +
-. From the table, locate ID for the authentication provider that you wish to delete
-. Delete the API key provider with this aura-cli statement
+. From the table, locate the ID for the authentication provider that you wish to delete.
+. Delete the API key provider with the following aura-cli statement.
 +
 [source, bash, indent=0]
 ----