M↓ View as Markdown ↗

Configuring Auth0¶

This guide describes how to create and configure an Auth0 API and Application for OAuth 2.0 authentication with the Actian MCP Server for Actian NoSQL.

Manual client registration

This guide focuses on manually created clients. Dynamic Client Registration (DCR) is not covered in this documentation.

By the completion of this guide, you will have obtained the issuer URL needed for quarkus.oidc.auth-server-url, as well as the Client ID and Client Secret (for Client Credentials flow) for the MCP client configuration.

Reference

Auth0 OpenID Connect documentation

Quick Start¶

Create a Database Connection: Navigate to Authentication > Database > + Create DB Connection if one does not exist.
Create users: Navigate to User Management > Users > + Create User for individuals who will log in via the Authorization Code flow.
Create an API: Navigate to Applications > APIs > + Create API. The "Identifier" becomes the audience for which MCP clients request tokens. Auth0 automatically creates a Machine to Machine application with access to this API and uses it directly for Client Credentials flow.
Add the write scope, in write mode only: add an mcp:write permission on the API's Permissions tab, turn on Enable RBAC under Settings > RBAC Settings, then grant it through a role under User Management > Roles. Each application also selects it on its own API Access tab.
Create an Application: Navigate to Applications > Applications > + Create Application. Choose Native, Regular Web Application, or Single Page Application. Copy the Client ID for the configuration.
Configure Allowed Callback URLs: Set the Allowed Callback URLs in the application settings to match the MCP client’s redirect URI.
Grant API access: Under the APIs tab of the application, authorize the API created in step 3.
Enable compatibility profile: Under Settings > Advanced, enable the Resource Parameter Compatibility Profile.
Update properties: Set quarkus.oidc.auth-server-url in application.properties to https://<your-tenant>.auth0.com/.
Start the server: Follow the standard server startup instructions as described in Start the Server documentation.

Prerequisites¶

An Auth0 account (sign up free)
An Auth0 Tenant (created automatically on signup, for example, dev-abc123)
The Actian MCP Server installed and ready to run

Step 1: Create a Database Connection¶

Create a database connection to authenticate users:

In the Auth0 Dashboard, navigate to Authentication > Database.
If no connection exists, select + Create DB Connection.
In the Name box, enter a name (for example, Username-Password-Authentication), and then select Create.

Step 2: Create Auth0 Users¶

Users represent the individuals who log in via the Authorization Code flow:

Note

This step is required only for the Authorization Code flow. Machine-to-machine (M2M) clients authenticate using their own credentials. No user account is required.

In the Auth0 Dashboard, navigate to User Management > Users.
Select + Create User.
Complete the following fields:

Field Value

Email jdoe@example.com

Password A strong password

Connection Username-Password-Authentication (default)
Select Create.

Step 3: Create an Auth0 API¶

The API represents the Actian MCP Server as a protected resource in Auth0. Tokens issued by Auth0 include the API identifier as the audience claim.

In the Auth0 Dashboard, go to Applications > APIs.
Select + Create API.

Configure the following settings:

Field	Value	Notes
Name	`Actian MCP Server`	Display name (any descriptive string)
Identifier (Audience)	`https://<mcp-server-host>:8443/mcp`	A logical identifier, it does not need to be a reachable URL.
Signing Algorithm	`RS256`	Default; leave as-is.

Select Create.

Step 3.1: Add the Write Scope (Write Mode Only)¶

Skip this step when nsql.writes.enabled is false. A read-only server never inspects the scope.

In write mode, the server checks every write call for the mcp:write scope and rejects a token that lacks it. Auth0 models that scope as a permission on the API, so this step defines the permission and turns on the setting that lets Auth0 issue it. You choose which applications receive it later, in Grant API Access. For what the server does with the scope, see Write support.

Define the Permission¶

Open the API you just created, for example Actian MCP Server, and select the Permissions tab.
Under Add a Permission, enter the following and select + Add:

Field Value

Permission mcp:write

Description Write access to NoSQL objects

Enable RBAC¶

On the API's Settings tab, scroll to RBAC Settings, turn on Enable RBAC, and select Save. With RBAC on, Auth0 checks what the caller holds before it fills the token's scope claim, which is the claim the server reads. If you leave RBAC off, Auth0 ignores the grant, and mcp:write never reaches the token.

Add Permissions in the Access Token is not needed

That neighboring toggle adds the same grants to a separate permissions claim. This server never reads that claim; the only claim it inspects is scope. Turning the toggle on causes no harm if another system in your environment needs it.

Grant It Through a Role¶

A role is how an interactive user receives the permission. Skip this section if you use only the Client Credentials flow, which has no user.

Navigate to User Management > Roles and select + Create Role. Name it, for example NoSQL MCP Writer, and select Create.
On the role's Permissions tab, select Add Permissions, choose your API, select mcp:write, and add it.
On the role's Users tab, select Add Users and assign everyone who is allowed to write.

Users outside that role continue to work as before: they read normally, and the server rejects a write attempt, naming the missing scope. Because the grant is per user, nobody obtains write access by asking for it.

Creating the permission gives it to nobody

Defining mcp:write on the API only makes it available to grant. Two separate things put it in a token: the application must be allowed to request it, which you set per application in Grant API Access, and an interactive user must hold it through the role above.

Auth0 can now issue the scope, but no client requests it until the server advertises it. That is a server setting, covered in Step 6.

Step 4: Create an Auth0 Application¶

The application represents the OAuth client, the MCP client (such as Claude Desktop or Cursor) that requests tokens on behalf of the user.

Machine-to-machine applications

When you created the API in Step 3, Auth0 automatically created an Machine-to-Machine application with client access granted to that API. You can use that application for the Client Credentials flow.

The following steps describe how to create an application for the interactive Authorization Code flow:

In the Auth0 Dashboard, navigate to Applications > Applications.
Select + Create Application.
Complete the following fields:

Field Value

Name MCP Client (or the name of your MCP client tool)

Application Type Native, Regular Web Application, or Single Page Application — depending on your MCP client.
Select Create. The Settings tab opens automatically.

Configure Application Settings¶

On the Settings tab, configure the redirect URI to match the MCP client's OAuth callback:

Setting	Value	Notes
Allowed Callback URLs	MCP client's callback URL	Consult the MCP client documentation for the exact value.
Allowed Logout URLs	MCP client's logout URL	Optional.
Allowed Web Origins	MCP client's origin	Optional, for CORS.

Select Save.

Grant API Access¶

This step allows the application to request tokens for the API and to choose which permissions it may request.

Go to the API Access tab of the application.

Select the Actian MCP Server API created in Step 3. A panel opens with two tabs, each covering a different kind of access:

Tab	Covers
User-Delegated Access	Tokens the application requests on behalf of a signed-in user — the Authorization Code flow.
Client Access	Tokens the application requests for itself, with no user involved — the Client Credentials flow.

Open the tab that matches the flow this application uses.
In write mode, select mcp:write from the permission list, then select Save.

Both flows need this, and the interactive one needs a role as well

The permission list controls what the application is allowed to request. For Client Credentials that is the entire grant, because there is no user whose role could carry it. For the Authorization Code flow it is only half: the signed-in user must also hold mcp:write through the role created in Step 3.1, or the token is issued without the scope.

Output of Step 4¶

Retain the following values for your MCP client configuration:

Value	Where to find it in Auth0
Client ID	Client ID on the Settings tab.
Client Secret	Client Secret on the Settings tab (only for the Machine to Machine client).

Step 5: Enable Resource Parameter Compatibility Profile¶

This is a tenant-level setting required for MCP clients to pass the audience parameter during the authorization flow:

In the Auth0 Dashboard, navigate to Settings.
Select the Advanced tab.
Enable Resource Parameter Compatibility Profile.
Select Save.

Step 6: Configure and Start the Server¶

The Actian MCP Server requires the Auth0 issuer URL to validate incoming tokens.

Mapping Summary¶

`application.properties` Property	Auth0 Source	Example Value
`quarkus.oidc.auth-server-url`	Your Auth0 tenant domain	`https://dev-abc123.us.auth0.com/`
`quarkus.oidc.resource-metadata.scopes`	—	`mcp:write`, in write mode only

Finding the Issuer URL

The issuer URL format is https://<your-domain>/. You can find the <your-domain> domain at the top of the Settings tab for any application. For example, dev-abc123.us.auth0.com.

Set the scopes list in write mode

Auth0 does not list custom API permissions in its OIDC discovery document, so a client that discovers its scopes never learns from Auth0 that mcp:write exists. Advertising the scope here is what makes the client request it. Without it, the whole Auth0 configuration from Step 3.1 stays invisible: the client authenticates cleanly and still cannot write.

A read-only server can leave the property unset. Auth0 issues a token without the scopes it will not grant, rather than refusing the request, so a client that requests more than it can obtain still authenticates. This is therefore a write-mode concern on Auth0, unlike Keycloak, where you should set it either way. For the mechanism, see Advertising scopes to MCP clients.

Example `application.properties`¶

Add the following to the application.properties and start the server as described in Start the Server:

nsql.connectionURL=<connection-url>
mcp.auth.enabled=true
quarkus.oidc.auth-server-url=https://dev-abc123.us.auth0.com/

In write mode, add quarkus.oidc.resource-metadata.scopes=mcp:write to the same file.

Verify End-to-End¶

Authorization Code Flow¶

After starting the Actian MCP Server with OAuth configured:

Connect to the server from your MCP client.
The MCP client fetches /.well-known/oauth-protected-resource and discovers the Auth0 issuer URL.
The MCP client redirects you to the Auth0 login page.
After logging in, Auth0 issues an access token to the MCP client.
The MCP client includes the Bearer token in all subsequent requests.
The server validates the token signature against Auth0's JWKS endpoint and grants access.

Client Credentials Flow¶

For automated clients using the Machine to Machine application:

The client authenticates directly with Auth0 using its Client ID and Client Secret.
Auth0 issues an access token without any user interaction.
The client includes the Bearer token in all requests to the MCP server.
The server validates the token signature against Auth0's JWKS endpoint and grants access.

Staging Versus Production¶

Environment	Recommendation
Development	Use a free Auth0 tenant. HTTP is acceptable for local testing (without TLS).
Staging / Production	Use a dedicated Auth0 tenant. Always enable TLS, see NoSQL TLS configuration for more information.

Field	Value
Email	`jdoe@example.com`
Password	A strong password
Connection	`Username-Password-Authentication` (default)

Field	Value
Permission	`mcp:write`
Description	`Write access to NoSQL objects`

Field	Value
Name	`MCP Client` (or the name of your MCP client tool)
Application Type	Native, Regular Web Application, or Single Page Application — depending on your MCP client.