How-To
Set Up OAuth2

How to Set Up OAuth2

This guide covers configuring NAT to authenticate against APIs protected by OAuth2 — the most common enterprise API auth standard.

Supported OAuth2 flows

Flow--oauth2-grant-typeBest for
Client Credentialsclient_credentialsService-to-service, automated testing
PasswordpasswordLegacy APIs with username/password auth
Authorization Codeauthorization_codeAPIs requiring interactive browser auth

For automated security testing, Client Credentials is strongly recommended.

Client Credentials flow

Create a test OAuth2 client

In your authorization server (Auth0, Okta, Keycloak, etc.), create a dedicated test client application with:

  • Grant type: Client Credentials
  • Scopes: All scopes needed to reach the endpoints you want to test

Keep the client_id and client_secret — you'll use them in the next step.

Verify the token endpoint

curl -X POST https://auth.example.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read write"

Confirm you get back an access token in the response.

Run NAT with OAuth2

nat scan \
  --url https://api.example.com \
  --auth-type oauth2 \
  --oauth2-token-url https://auth.example.com/oauth/token \
  --oauth2-client-id YOUR_CLIENT_ID \
  --oauth2-client-secret YOUR_CLIENT_SECRET \
  --oauth2-scope "read write"

NAT will fetch a token before scanning and automatically refresh it if it expires during a long scan.

Password grant flow

⚠️

The Resource Owner Password Credentials (ROPC) grant is deprecated in OAuth 2.1 and should not be used in new systems. Use it only when testing legacy APIs that don't support client credentials.

nat scan \
  --url https://api.example.com \
  --auth-type oauth2 \
  --oauth2-grant-type password \
  --oauth2-token-url https://auth.example.com/oauth/token \
  --oauth2-client-id YOUR_CLIENT_ID \
  --oauth2-client-secret YOUR_CLIENT_SECRET \
  --oauth2-username testuser@example.com \
  --oauth2-password "$TEST_USER_PASSWORD" \
  --oauth2-scope "read write"

Provider-specific examples

nat scan \
  --url https://api.example.com \
  --auth-type oauth2 \
  --oauth2-token-url https://YOUR_DOMAIN.auth0.com/oauth/token \
  --oauth2-client-id YOUR_CLIENT_ID \
  --oauth2-client-secret YOUR_CLIENT_SECRET \
  --oauth2-audience https://api.example.com

Note: Auth0 requires an audience parameter instead of scope.

Using secrets safely in CI

Never put OAuth2 credentials directly in YAML files. Use CI secrets:

# GitHub Actions
- uses: bg-playground/nat-action@v1
  with:
    api-url: https://api.example.com
    auth-type: oauth2
    oauth2-token-url: https://auth.example.com/oauth/token
    oauth2-client-id: ${{ secrets.OAUTH2_CLIENT_ID }}
    oauth2-client-secret: ${{ secrets.OAUTH2_CLIENT_SECRET }}
    oauth2-scope: "read write"

Troubleshooting OAuth2 issues

See Auth Issues troubleshooting for help with:

  • Token fetch failures (401, 400 responses from token endpoint)
  • invalid_scope errors
  • Token expiry during long scans
  • mTLS and PKCE requirements

Next steps

Customize Security ChecksIntegrate with GitHub Actions