diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index c61978c..d32a7be 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -56,14 +56,6 @@ * *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:aura-graphql/end-of-beta-phase.adoc[] - - * xref:introspector.adoc[Introspector] * *Frameworks and integrations* diff --git a/modules/ROOT/pages/aura-graphql/authentication-providers.adoc b/modules/ROOT/pages/aura-graphql/authentication-providers.adoc deleted file mode 100644 index fc36453..0000000 --- a/modules/ROOT/pages/aura-graphql/authentication-providers.adoc +++ /dev/null @@ -1,102 +0,0 @@ -[[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/deploy-and-operate.adoc b/modules/ROOT/pages/aura-graphql/deploy-and-operate.adoc deleted file mode 100644 index db75c3b..0000000 --- a/modules/ROOT/pages/aura-graphql/deploy-and-operate.adoc +++ /dev/null @@ -1,81 +0,0 @@ -= 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 ----- - -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. -==== diff --git a/modules/ROOT/pages/aura-graphql/end-of-beta-phase.adoc b/modules/ROOT/pages/aura-graphql/end-of-beta-phase.adoc deleted file mode 100644 index 5b00402..0000000 --- a/modules/ROOT/pages/aura-graphql/end-of-beta-phase.adoc +++ /dev/null @@ -1,140 +0,0 @@ -= End of beta phase - -The beta phase of GraphQL for Neo4j AuraDB will end on the 18th of April 2025. -To prevent data loss and wrap up your beta experience we suggest you take the following steps: - -* Backup GraphQL Data API configuration -* Remove the GraphQL Data API -* Provide feedback - -You are not required to take action. -However, any running GraphQL Data API will be terminated after the 18th of April, resulting in the loss of its configuration information including type definitions. - - -== Backup the GraphQL Data API configuration - -Backing up your GraphQL Data API configuration makes re-use much quicker if you decide to use this feature once it is released. -If you want to run your own GraphQL service instead, the backup might still be useful since it includes the type definitions which can be used for that purpose. - -There are two ways to perform a backup: - -* Manually copy them one by one from the Aura Console -* Using the Aura CLI to obtain everything in a single operation - - -=== Console - -If you want to retain only parts of the configuration, this is a quick method to do so. -If you are intent on backing up all of the configuration, use the xref:#_aura_cli[] instead. - -1. On Aura Console, select **Data API** from the left side navigation. -+ -image::aura-graphql/console_data_api_sidebar.png[] -+ -2. The table shows your GraphQL Data APIs. Use the three dots on the row with the GraphQL Data API that you wish to backup and select **Edit**. -+ -image::aura-graphql/console_data_api_edit_menu.png[] -+ -3. Expand each of the sections and then make a note of the setting or copy as necessary. -+ -image::aura-graphql/console_data_api_edit.png[] - - -=== Aura CLI - -This section assumes that you have configured the Aura CLI. -If you have not, follow the guidance provided in xref:aura-graphql/prerequisites.adoc#_install_and_configure_the_aura_cli[]. - - -1. Look up the Aura instance ID that the GraphQL API is being used with. -+ -[source, bash, indent=0] ----- -aura-cli instance list --output table ----- -+ - -2. From the displayed table, make a note of relevant Aura ID. Use this ID to obtain the ID of the GraphQL API whose configuration you want to back up. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID --output table ----- -+ - -3. Finally, obtain the configuration of the GraphQL API itself in JSON format. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql get YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID ----- -+ -4. Save the output for future use. - -[NOTE] -==== -Type definitions are stored using Base64 encoding. -Decode them to plain text before using with other systems. -==== - - -== Removing the GraphQL Data API - -Remove the GraphQL Data API either via Aura Console or with the Aura CLI. - -[WARNING] -==== -Once the GraphQL Data API has been deleted, it cannot be recovered. -==== - - -=== Console - -1. In Aura Console, select **Data API** from the left side navigation. -+ -image::aura-graphql/console_data_api_sidebar.png[] -+ -2. The table contains your GraphQL Data APIs. Use the three dots on the row with the GraphQL Data API that you wish to remove and select **Delete**. -+ -image::aura-graphql/console_data_api_delete_menu.png[] -+ -3. Type in the name of your GraphQL API and confirm with **Delete**. -+ -image::aura-graphql/console_data_api_confirm_delete_menu.png[] - - -=== Aura CLI - -This section assumes that you have configured the Aura CLI. -If you have not, follow the guidance provided in xref:aura-graphql/prerequisites.adoc#_install_and_configure_the_aura_cli[]. - -1. Locate the Aura instance ID that the GraphQL API is being used with. -+ -[source, bash, indent=0] ----- -aura-cli instance list --output table ----- -+ -2. From the displayed table, make a note of the relevant Aura ID. Use the ID to obtain the ID of the GraphQL API whose configuration you want to back up. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID --output table ----- -+ -3. Delete the GraphQL API. -+ -[WARNING] -==== -The Aura CLI does not ask for confirmation and processes the command immediately. -==== -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql delete YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --output table ----- - - -== Provide feedback - -Please consider taking a few moments to provide feedback either by creating an issue in our link:https://github.com/neo4j/graphql/issues/new/choose[GitHub repository] or using 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]. diff --git a/modules/ROOT/pages/aura-graphql/index.adoc b/modules/ROOT/pages/aura-graphql/index.adoc deleted file mode 100644 index d4f6f1a..0000000 --- a/modules/ROOT/pages/aura-graphql/index.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= 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/prerequisites.adoc b/modules/ROOT/pages/aura-graphql/prerequisites.adoc deleted file mode 100644 index 589b61b..0000000 --- a/modules/ROOT/pages/aura-graphql/prerequisites.adoc +++ /dev/null @@ -1,218 +0,0 @@ -= 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/unified-console-home.png[] -+ -3. In the menu, click *API keys*. -+ -image::aura-graphql/unified-console-account-dropdown.png[] -+ -4. Click *Create*. -+ -image::aura-graphql/unified-console-api-keys.png[] -+ -5. In the pop-up window, enter a name for the API Key and click *Create*. -+ -image::aura-graphql/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/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/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/using-your-api.adoc b/modules/ROOT/pages/aura-graphql/using-your-api.adoc deleted file mode 100644 index 89fd172..0000000 --- a/modules/ROOT/pages/aura-graphql/using-your-api.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= 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 -----