Merge branch '6.x' into add-new-deprecations-and-typename_IN

Author: MacondoExpress

modules/ROOT/content-nav.adoc

@@ -58,6 +58,12 @@
 
 * *Products*
 
+* xref:aura-graphql/index.adoc[]
+** xref:aura-graphql/prerequisites.adoc[]
+** xref:aura-graphql/deploy-and-operate.adoc[]
+** xref:aura-graphql/authentication-providers.adoc[]
+** xref:aura-graphql/using-your-api.adoc[]
+
 * xref:introspector.adoc[Introspector]
 
 * *Frameworks and integrations*

modules/ROOT/images/aura-graphql/console-classic-api-keys.png

@@ -0,0 +1,102 @@
+[[auth-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 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.
+====
+
+== Creating a JWKS authentication provider
+
+Before using JWKS authentication providers, you must set up and configure an identity provider that:
+
+ * 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 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 its 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 responds with details about the newly created JWKS 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 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, 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:
+
+[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.
+====
+
+== Listing 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
+----
+
+== 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.
+
+. 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 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]
+----
+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/images/aura-graphql/console-classic-home.png

@@ -0,0 +1,81 @@
+= Deploy and operate
+
+== Deploy a GraphQL API
+
+
+Before you deploy a GraphQL API, complete the steps in xref::/aura-graphql/prerequisites.adoc[Prerequisites].
+Make sure that you have:
+
+* The ID, username and password for the AuraDB.
+* A file containing the type definitions.
+
+You are now ready to create the GraphQL API with the Aura CLI.
+Substitute the values in `CAPITALS` to match your setup:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql create --name YOUR_FRIENDLY_NAME --instance-id YOUR_AURA_INSTANCE_ID --instance-username YOUR_AURA_INSTANCE_USER --instance-password YOUR_AURA_INSTANCE_PASSWORD --type-definitions-file
+FULL_PATH_TO_YOUR_TYPE_DEFS --await
+----
+
+[NOTE]
+====
+Make sure to record the API key shown in the response as it will not be displayed again.
+If the API key is lost, a new one can be created by following the steps to create a new API key auth provider in xref::/aura-graphql/authentication-providers.adoc[Authentication providers].
+====
+
+There are other items of note in the response:
+
+* `id`: unique identifier for the GraphQL API
+* `status`: tells you if the GraphQL API is ready to receive requests
+* `url`: the connection address to access the GraphQL API
+
+To check if the GraphQL API is ready for requests, use the Aura CLI again, changing `YOUR_AURA_INSTANCE_ID` for the ID of your aura instance.
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID
+----
+
+When the status changes to `ready`, the GraphQL API is available for servicing requests.
+
+== Modifying an existing GraphQL API
+
+It is possible to change the configuration of an existing GraphQL API.
+The following properties can be modified:
+
+* Friendly name of the GraphQL API
+* Username and/or password for the associated Aura instance
+* Type definitions
+
+To do this, use the Aura CLI update command which requires IDs of the GraphQL API and its linked AuraDB instance.
+The format of this Aura CLI command is as follows:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql update YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID <flags>
+----
+
+As the change takes a few moments to apply, check the status of the GraphQL API after performing this operation.
+If the status is `updating` then the change is still being processed.
+When the change is committed, the status will return to `ready`.
+
+Additionally, it is possible to modify the authentication providers of GraphQL APIs.
+To learn more, see xref::/aura-graphql/authentication-providers.adoc[Authentication providers].
+
+== Deleting a GraphQL API
+
+When you no longer require the GraphQL API then delete it by using the Aura CLI delete command.
+This requires the Aura instance ID and the ID of the GraphQL API.
+
+The format of this command is as follows:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql delete YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID
+----
+
+[CAUTION]
+====
+There is no additional confirmation - the GraphQL API will start to be deleted as soon as you execute the command.
+====

modules/ROOT/images/aura-graphql/unified-console-account-dropdown.png

@@ -0,0 +1,16 @@
+= GraphQL for Neo4j AuraDB Beta
+
+Welcome to the beta release of GraphQL for Neo4j AuraDB.
+
+Your feedback and insights help us refine and evolve the product and meet the needs of our users.
+
+The beta release is designed to give you a first look at GraphQL for Neo4j AuraDB.
+You may encounter suboptimal behavior.
+
+You can help us get GraphQL for Neo4j AuraDB ready for production:
+
+- *Dive in*: Explore and test its features.
+- *Test the product limits*: We'd rather discover weak areas at this stage.
+- *Share your experience*: Tell us what works, what doesn't, and what you'd like to see in the future.
+- *Provide feedback*: Use our `#graphql` channel on our link:https://discord.gg/M8mTADEJ[Discord Community], or our link:https://community.neo4j.com/c/drivers-stacks/graphql/33[forums] to report issues, suggest improvements, or ask questions.
+