diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index fa3e1352..2efddf1a 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -59,6 +59,12 @@ * *Products* +* xref:aura-graphql-data-apis/index.adoc[] +** 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] * xref:ogm/index.adoc[] diff --git a/modules/ROOT/images/aura-graphql-data-apis/console-classic-api-keys.png b/modules/ROOT/images/aura-graphql-data-apis/console-classic-api-keys.png new file mode 100644 index 00000000..e7b7ecff Binary files /dev/null and b/modules/ROOT/images/aura-graphql-data-apis/console-classic-api-keys.png differ diff --git a/modules/ROOT/images/aura-graphql-data-apis/console-classic-home.png b/modules/ROOT/images/aura-graphql-data-apis/console-classic-home.png new file mode 100644 index 00000000..e43c629b Binary files /dev/null and b/modules/ROOT/images/aura-graphql-data-apis/console-classic-home.png differ diff --git a/modules/ROOT/images/aura-graphql-data-apis/unified-console-account-dropdown.png b/modules/ROOT/images/aura-graphql-data-apis/unified-console-account-dropdown.png new file mode 100644 index 00000000..b57800a0 Binary files /dev/null and b/modules/ROOT/images/aura-graphql-data-apis/unified-console-account-dropdown.png differ diff --git a/modules/ROOT/images/aura-graphql-data-apis/unified-console-api-keys.png b/modules/ROOT/images/aura-graphql-data-apis/unified-console-api-keys.png new file mode 100644 index 00000000..78dd6459 Binary files /dev/null and b/modules/ROOT/images/aura-graphql-data-apis/unified-console-api-keys.png differ diff --git a/modules/ROOT/images/aura-graphql-data-apis/unified-console-create-api-key.png b/modules/ROOT/images/aura-graphql-data-apis/unified-console-create-api-key.png new file mode 100644 index 00000000..be651acc Binary files /dev/null and b/modules/ROOT/images/aura-graphql-data-apis/unified-console-create-api-key.png differ diff --git a/modules/ROOT/images/aura-graphql-data-apis/unified-console-home.png b/modules/ROOT/images/aura-graphql-data-apis/unified-console-home.png new file mode 100644 index 00000000..53b11d04 Binary files /dev/null and b/modules/ROOT/images/aura-graphql-data-apis/unified-console-home.png differ diff --git a/modules/ROOT/pages/aura-graphql-data-apis/authentication-providers.adoc b/modules/ROOT/pages/aura-graphql-data-apis/authentication-providers.adoc new file mode 100644 index 00000000..fc364539 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql-data-apis/authentication-providers.adoc @@ -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 +---- diff --git a/modules/ROOT/pages/aura-graphql-data-apis/deploy-and-operate.adoc b/modules/ROOT/pages/aura-graphql-data-apis/deploy-and-operate.adoc new file mode 100644 index 00000000..b25c0481 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql-data-apis/deploy-and-operate.adoc @@ -0,0 +1,81 @@ += Deploy and operate + +== Deploy a GraphQL API + + +Before you deploy a GraphQL API, complete the steps in xref::/aura-graphql-data-apis/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-data-apis/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 +---- + +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-data-apis/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. +==== diff --git a/modules/ROOT/pages/aura-graphql-data-apis/index.adoc b/modules/ROOT/pages/aura-graphql-data-apis/index.adoc new file mode 100644 index 00000000..d4f6f1a9 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql-data-apis/index.adoc @@ -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. + diff --git a/modules/ROOT/pages/aura-graphql-data-apis/prerequisites.adoc b/modules/ROOT/pages/aura-graphql-data-apis/prerequisites.adoc new file mode 100644 index 00000000..9848fa34 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql-data-apis/prerequisites.adoc @@ -0,0 +1,218 @@ += Prerequisites + +The beta of GraphQL for Neo4j AuraDB is managed via the Aura CLI command line tool. +You must install and configure the Aura CLI for this purpose. +Future versions will be fully integrated with the Aura Console. + +== Before you start + +Using the GraphQL API during the Open Beta is free of charge. +Usage of the associated AuraDB instance will be charged as normal unless you're using Aura Pro Trials which is a zero-cost option. + +At the end of the beta period, all running GraphQL endpoints will be terminated in preparation for the full release. +We will send out a notification two weeks before they are terminated. + + +== Obtain Aura API credentials + +The Aura CLI communicates with Neo4j AuraDB platform via an API. +To use the API, a set of credentials is required. +To get the credentials, follow these steps depending on which version of the console you are using. + +=== New unified Aura Console experience + +1. Log in to the link:https://console.neo4j.io/[Neo4j Aura Console]. +2. Navigate to the top right where your account name is displayed and click the down arrow. ++ +image::aura-graphql-data-apis/unified-console-home.png[] ++ +3. In the menu, click *API keys*. ++ +image::aura-graphql-data-apis/unified-console-account-dropdown.png[] ++ +4. Click *Create*. ++ +image::aura-graphql-data-apis/unified-console-api-keys.png[] ++ +5. In the pop-up window, enter a name for the API Key and click *Create*. ++ +image::aura-graphql-data-apis/unified-console-create-api-key.png[] ++ +6. The client ID and client secret are displayed. Make a note as the client secret will not be shown again and you need both. If you download them, keep them safe. + +=== Aura Console classic + +1. Log in to the link:https://console.neo4j.io/[Neo4j Aura Console]. +2. Navigate to the top right where your account name is displayed and click the down arrow. ++ +image::aura-graphql-data-apis/console-classic-home.png[] ++ +3. A menu with your account name is displayed. Click *Account Details*. +4. In the *Account Details* menu, click *Create* in the *Aura API* credentials section. ++ +image::aura-graphql-data-apis/console-classic-api-keys.png[] ++ +5. In the pop-up window, enter a client name and click *Create*. +6. The newly created client ID and client secret are displayed. Make sure to securely save these as they are required to use the Aura CLI. + +== Install and configure the Aura CLI + +=== Installation + +. Navigate to link:https://github.com/neo4j/aura-cli/releases/tag/v1.1.0[https://github.com/neo4j/aura-cli/releases/tag/v1.1.0] in your browser. ++ +[NOTE] +==== +Use Aura CLI version 1.1.0 or higher for managing your GraphQL APIs. +==== ++ +. Download the compressed file that matches your system. Make a note of the folder where the file is located. +. After the file has been downloaded, extract the contents. +. Open a command prompt and move to the location where you extracted the files. +. Complete the installation by moving the aura-cli executable file into the file path. +.. Mac/Linux users: ++ +[source, bash, indent=0] +---- +sudo mv aura-cli /usr/local/bin +---- ++ +.. Windows users: ++ +[source, cmd, indent=0] +---- +move aura-cli c:\windows\system32 +---- ++ +. At the command prompt, type: ++ +[source, bash, indent=0] +---- +aura-cli -v +---- ++ +. You should see this: ++ +[source, bash, indent=0] +---- +aura version v1.1.0 +---- + +[NOTE] +==== +If you are using a Mac, you may receive a warning from Apple that aura-cli could not be verified. +If this happens, open *System Settings*, click *Privacy & Security* on the left, and scroll down on the right. +Click *Open Anyway*. +This should not happen again. +The aura-cli has been through the Apple certification process but it can take time to trickle down through the Apple ecosystem. +==== + +=== Add Aura API credentials + +Configure the Aura CLI with the Aura API client ID and client secret you obtained earlier. +The Aura CLI refers to these as credentials and it is possible to have several sets of credentials and then choose which one to use. + +. At the command prompt, enter the following, using your values for the items in CAPITALS: ++ +[source, bash, indent=0] +---- +aura-cli credential add --name YOUR_LABEL --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET +---- ++ +. To confirm the credentials are working, list your Aura instances: ++ +[source, bash, indent=0] +---- +aura-cli instance list --output table +---- + + +=== Set the beta flag + +Instruct the Aura CLI to make available the commands for the open beta. +This requires setting a configuration option. + +. At the command prompt, enter the following: ++ +[source, bash, indent=0] +---- +aura-cli config set beta-enabled true +---- ++ +. Check if the commands are listed for the open beta: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql +---- ++ +. You should see this: ++ +[source, bash, indent=0] +---- +Allows you to programmatically provision and manage your GraphQL APIs + +Usage: + aura-cli data-api graphql [command] + +Available Commands: + auth-provider Allows you to programmatically manage Authentication providers for a specific GraphQL Data API + cors-policy Allows you to manage the Cross-Origin Resource Sharing (CORS) policy for a specific GraphQL Data API + create Creates a new GraphQL Data API + delete Delete a GraphQL Data API + get Get details of a GraphQL Data API + list Returns a list of GraphQL Data APIs + pause Pause a GraphQL Data API + resume Resume a GraphQL Data API + update Edit a GraphQL Data API + +Flags: + -h, --help help for graphql + +Global Flags: + --auth-url string + --base-url string + --output string + +Use "aura-cli data-api graphql [command] --help" for more information about a command. +---- + +== Write GraphQL type definitions + +Before you create a GraphQL API for use with an Aura instance, you must create type definitions. + +If you already have type definitions from an existing GraphQL implementation these can be used. +However, you must deal with some exceptions. +The following are not currently supported: + +* The `@customResolver` and `@populatedBy` directives +* Subscriptions + +Using the link:https://graphql-toolbox.neo4j.io/[Neo4j GraphQL Toolbox] is an easy way to produce and try out type definitions. +Use of the Toolbox requires a connection to your Aura instance. + +[NOTE] +==== +The *Neo4j GraphQL Toolbox* currently,supports version 6 of the `@neo4j/graphql` library. +However, GraphQL APIs run the version 7 alpha. +As a result, type definitions created via the toolbox may not be valid with a GraphQL API. +You can find a list of the breaking changes link:https://github.com/neo4j/graphql/releases?q=%40neo4j%2Fgraphql%407.0.0-alpha&expanded=true[here]. +==== + +When your type definitions are ready, save them to a file. +They will be used with the Aura CLI to create the GraphQL API. + +== Select the AuraDB instance + +At the command prompt, type: + +[source, bash, indent=0] +---- +aura-cli instance list +---- + +Your AuraDB instances are displayed along with their IDs. +Make a note of the ID of the AuraDB instance that you will use with the GraphQL API. + +After choosing an AuraDB to use and obtaining its ID, you must also have its username and password to use for authentication. +For AuraDB, the username will likely be "neo4j" and the password has been shown when it was created. diff --git a/modules/ROOT/pages/aura-graphql-data-apis/using-your-api.adoc b/modules/ROOT/pages/aura-graphql-data-apis/using-your-api.adoc new file mode 100644 index 00000000..89fd1726 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql-data-apis/using-your-api.adoc @@ -0,0 +1,60 @@ += Using your GraphQL API + +== Querying your GraphQL API + +When 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 and 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 and 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' +---- + +== Querying your GraphQL API from a browser + +=== CORS Policy + +For security reasons, browsers restrict cross-origin requests to servers. +This means that by default, if you configure a web app to make a request to your GraphQL APIs from a browser, it will fail. +This is because your web app is hosted at a different origin than your GraphQL API. + +However, most modern browsers support Cross-Origin Resource Sharing (CORS). +This involves the browser sending a "preflight" request to the server to check that it will allow the actual request. +You can configure your GraphQL APIs to allow cross-origin requests from your web app by adding it to the list of allowed origins. +For example, if you expect requests to be made by a web app hosted at `https://example.com`, this should be added to the list of allowed origins for your GraphQL API. + +[NOTE] +==== +Only exact matches for allowed origins are supported - wildcards (*) will do not work. +==== + +Use the aura-cli and the following command, replacing the UPPERCASE values as required: + +[source, bash, indent=0] +---- +aura-cli data-api graphql cors-policy allowed-origin add NEW_ALLOWED_ORIGIN --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- + +Allowed origins that are no longer required can be removed with the following command, replacing the UPPERCASE values as required: + +[source, bash, indent=0] +---- +aura-cli data-api graphql cors-policy allowed-origin remove OLD_ALLOWED_ORIGIN --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +----