Authentication providers

This is the documentation of the GraphQL Library version 6. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

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.

--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 @authentication and @authorization directives of GraphQL for Neo4j AuraDB.

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:

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

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:

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.

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.

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.

  1. Find the API authentication provider ID.

    aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --output table

  2. From the table, locate the ID for the authentication provider that you wish to delete.

  3. Delete the API key provider with the following aura-cli statement.

    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