Add authentication provider and usage docs

Author: Liam-Doodson

modules/ROOT/content-nav.adoc

@@ -62,6 +62,7 @@
 ** xref:aura-graphql-data-apis/prerequisites.adoc[]
 ** xref:aura-graphql-data-apis/deploy-and-operate.adoc[]
 ** xref:aura-graphql-data-apis/authentication-providers.adoc[]
+** xref:aura-graphql-data-apis/using-your-api.adoc[]
 
 * xref:introspector.adoc[Introspector]
 

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

@@ -1,2 +1,79 @@
 [[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.
+
+There are advantages and disadvantages of both types. API keys are quick to start working with but do not allow for access controls. 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.
+====
+
+== Create a JWKS Authentication Provider
+
+Before using JWKS, 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.
+
+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.
+
+[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.
+====
+
+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.
+
+At a command prompt, type the following, swapping out the UPPERCASE values for your own:
+
+[source, bash, indent=0]
+----
+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.
+
+== Create an API Key Authentication Provider
+
+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.
+
+At a command prompt, type the following, swapping out the UPPERCASE values for your own:
+
+[source, bash, indent=0]
+----
+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 api-key
+----
+
+On success, the command will respond with details about the newly created API Key.
+
+[NOTE]
+====
+Make sure to record the API key shown in the response as it will not be displayed again.
+====
+
+== List Authentication Providers
+
+To see the list of authentication providers for a given GraphQL API use the following, exchanging UPPERCASE values for your own.
+
+[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
+----
+
+== Delete 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.
+
+. 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
++
+[source, bash, indent=0]
+----
+aura-cli data-api graphql auth-provider delete AUTH-PROVIDER-ID --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID
+----

modules/ROOT/pages/aura-graphql-data-apis/using-your-api.adoc

@@ -0,0 +1,23 @@
+= Using your GraphQL API
+
+Once the status for the GraphQL API is `ready` you can send GraphQL requests to it. As all requests are subject to authentication, you must include an API key or JWT token.
+
+== With an API Key Authentication Provider
+
+Add `x-api-key: YOUR_API_KEY` to the header of the request. For example, with curl replacing the UPPERCASE values with those of your own:
+
+[source, bash, indent=0]
+----
+curl --location YOUR_GRAPHQL_API_URL --header 'Content-Type: application/json' --header 'x-api-key: YOUR_API_KEY' --data 'YOUR_GRAPHQL_QUERY'
+----
+
+== With a JWKS Authentication Provider
+
+Obtain a JWT from your identity provider. Using the JWT, add `Authorization: Bearer YOUR_JWT` to the headers of the request.
+
+For example, with curl replacing the UPPERCASE values with those of your own:
+
+[source, bash, indent=0]
+----
+curl --location  YOUR_GRAPHQL_API_URL --header 'Authorization: Bearer YOUR_JWT'--header 'Content-Type: application/json --data 'YOUR_GRAPHQL_QUERY'
+----