Configure custom JWT authentication (Okta, Auth0)

Data API builder supports third-party identity providers through the Custom authentication provider using JSON Web Token (JWT) validation. Use this approach when your organization uses Okta, Auth0, or another OAuth 2.0/OpenID Connect-compliant identity provider.

Authentication flow

With a custom identity provider, your client app handles user authentication and then sends the access token to Data API builder:

Prerequisites

• An account with your identity provider (Okta, Auth0, etc.)
• An application registered in your identity provider
• Data API builder CLI installed (installation guide)
• An existing dab-config.json with at least one entity

Quick reference

Step 1: Configure your identity provider

The exact steps depend on your provider. Here are the key values you need:

Values to collect

Okta example

1. Sign in to the Okta Admin Console.
2. Navigate to Applications > Applications.
3. Create or select an application.
4. Note the Client ID (use as audience).
5. Your issuer is typically https://<your-domain>.okta.com.

Auth0 example

1. Sign in to the Auth0 Dashboard.
2. Navigate to Applications > APIs.
3. Create or select an API.
4. Note the Identifier (use as audience).
5. Your issuer is https://<your-tenant>.auth0.com/.

Step 2: Configure Data API builder

Set the authentication provider to Custom and configure the JWT settings:

CLI

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider Custom

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider Custom

REM Set the expected audience
dab configure ^
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

REM Set the expected issuer
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

Resulting configuration

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

Step 3: Configure entity permissions

Define permissions for the roles your identity provider assigns:

CLI

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

REM Allow users with 'admin' role full access
dab update Book ^
  --permissions "admin:*"

Resulting configuration

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Step 4: Configure roles in your identity provider

DAB expects roles in a roles claim. Configure your identity provider to include this claim.

Okta: Add groups as roles

1. In the Okta Admin Console, go to Security > API.
2. Select your authorization server.
3. Go to the Claims tab.
4. Add a claim:
   • Name: roles
   • Include in token type: Access Token
   • Value type: Groups
   • Filter: Select the groups to include

Auth0: Add roles with an Action

Auth0 requires custom claims to use collision-resistant, namespaced names (for example, https://example.com/roles). Non-namespaced claims that collide with reserved names are silently excluded from the token. For more information, see Create custom claims in the Auth0 documentation.

Data API builder expects the exact claim name roles, not a namespaced variant. Whether Auth0 accepts a non-namespaced roles claim depends on your tenant configuration.

1. In the Auth0 Dashboard, go to Actions > Library.

2. Create a new Action (Post Login trigger).

3. Add code to include roles:

   exports.onExecutePostLogin = async (event, api) => {
     const roles = event.authorization?.roles || [];
     if (roles.length > 0) {
       api.accessToken.setCustomClaim('roles', roles);
     }
   };
   

4. Deploy the Action and add it to your Login flow.

5. Verify the decoded access token at jwt.io and confirm the roles claim is present.

Step 5: Test the configuration

1. Start Data API builder:

   dab start
   

2. Acquire a token from your identity provider. Use your provider's SDK or a tool like Postman.

3. Inspect the token at jwt.io to verify:

   • The aud claim matches your configured audience
   • The iss claim matches your configured issuer
   • The roles claim contains the expected values

4. Call the API:

   curl -X GET "http://localhost:5000/api/Book" \
     -H "Authorization: Bearer <your-token>"
   

5. To use a custom role, include the X-MS-API-ROLE header:

   curl -X GET "http://localhost:5000/api/Book" \
     -H "Authorization: Bearer <your-token>" \
     -H "X-MS-API-ROLE: admin"
   

JWT validation details

Data API builder validates these aspects of the JWT:

Troubleshooting

Common issuer formats

Complete configuration example

Okta configuration

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Auth0 configuration

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Related content

• Authorization overview
• Configure Microsoft Entra ID authentication
• Configure Simulator authentication for testing
• Runtime configuration reference