Skip to main content
API7.ai Logo
Version: 3.18.0

Set Up SSO with Auth0

OpenID Connect (OIDC) adds an identity layer to OAuth 2.0, allowing applications to verify an end user's identity and obtain basic profile information from an identity provider (IdP). In a single sign-on (SSO) deployment, users authenticate through the IdP and can access connected applications without signing in separately to each one.

Auth0 is a cloud identity platform that can serve as the centralized IdP for applications and APIs. It provides Universal Login, identity-provider connections, multi-factor authentication, and access policies. In this integration, Apache APISIX delegates browser authentication to Auth0 before proxying requests to an upstream service.

The guide shows how to configure APISIX and Auth0 for the OIDC Authorization Code flow with Proof Key for Code Exchange (PKCE). When a request does not have a valid APISIX session, APISIX redirects the browser to Auth0. After successful authentication, APISIX exchanges the authorization code for tokens, creates a browser session, and resumes the original request.

Prerequisite(s)​

Configure Auth0​

Register a regular web application in Auth0, then save its domain and client credentials for the APISIX route.

Create an Application​

Sign in to the Auth0 Dashboard and create the application:

  1. Select Applications → Applications → Create Application.
  2. Enter APISIX Authorization Code as the application name.
  3. Select Regular Web Application.
  4. Select Create.

On the application's Settings tab, configure the callback:

  1. Under Application URIs, add http://localhost:9080/anything/user/callback to Allowed Callback URLs.
  2. Select Save Changes.

Configure the Auth0 application callback URL for APISIX

The callback URL identifies the APISIX endpoint where Auth0 returns the browser after authentication. In production, use an HTTPS endpoint that users can reach and register that exact URL in Auth0.

Save the OIDC Configuration​

On the application's Settings tab, record the Domain, Client ID, and Client Secret. Save them to environment variables, replacing the example values:

export AUTH0_DOMAIN=your-tenant.us.auth0.com
export AUTH0_CLIENT_ID=replace-with-your-client-id
export AUTH0_CLIENT_SECRET=replace-with-your-client-secret
export AUTH0_DISCOVERY="https://${AUTH0_DOMAIN}/.well-known/openid-configuration"

Keep the client secret confidential. Store production credentials in a secret manager and rotate them according to the organization's credential-rotation policy.

Configure APISIX​

Configure a route that authenticates browser requests before forwarding them to httpbin.org, a public HTTP request and response service. The /anything/user/* endpoint returns request details for verification.

Generate a unique secret that APISIX will use to encrypt and authenticate the browser session cookie:

export APISIX_SESSION_SECRET="$(openssl rand -hex 32)"

Choose either the Admin API or ADC to configure the route.

Create the route through the Admin API:

curl "http://127.0.0.1:9180/apisix/admin/routes/auth0-sso" -X PUT \
  --data-binary @- <<EOF
{
  "uri": "/anything/user/*",
  "plugins": {
    "openid-connect": {
      "client_id": "$AUTH0_CLIENT_ID",
      "client_secret": "$AUTH0_CLIENT_SECRET",
      "discovery": "$AUTH0_DISCOVERY",
      "redirect_uri": "http://localhost:9080/anything/user/callback",
      "bearer_only": false,
      "use_pkce": true,
      "scope": "openid profile email",
      "session": {
        "secret": "$APISIX_SESSION_SECRET"
      },
      "set_access_token_header": false,
      "set_id_token_header": false,
      "set_userinfo_header": false
    },
    "proxy-rewrite": {
      "headers": {
        "remove": ["Authorization", "Cookie"]
      }
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}
EOF

❶ discovery: URI of the Auth0 tenant's OIDC discovery document.

❷ redirect_uri: URI where Auth0 returns the browser after authentication. It must match the callback URL configured in Auth0.

❸ bearer_only and use_pkce: Start browser authentication when no valid session exists and send an S256 PKCE challenge during authorization.

❹ set_access_token_header, set_id_token_header, and set_userinfo_header: Set to false to prevent APISIX from adding tokens and user information to upstream request headers.

❺ proxy-rewrite.headers.remove: Removes the original authorization header and the entire cookie header, including the APISIX session cookie, before proxying the request. Review this setting if the upstream application requires cookies.

Verify Authentication​

Navigate to http://localhost:9080/anything/user/get in a browser. APISIX redirects you to Auth0. If you do not have an active Auth0 session, Auth0 prompts you to sign in.

Auth0 Universal Login for the APISIX application

Complete the Auth0 sign-in. If Auth0 asks you to authorize the application, select Accept. After successful authentication, Auth0 returns the browser to APISIX, and APISIX forwards the request to httpbin.org. The response should contain fields similar to these:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate",
    "Accept-Language": "en-CA,en-US;q=0.9,en;q=0.8",
    "Host": "localhost",
    "Priority": "u=0, i",
    "Sec-Fetch-Dest": "document",
    "Sec-Fetch-Mode": "navigate",
    "Sec-Fetch-Site": "cross-site",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.6 Safari/605.1.15",
    "X-Amzn-Trace-Id": "Root=1-...",
    "X-Forwarded-Host": "localhost:9080"
  },
  "json": null,
  "method": "GET",
  "origin": "192.168.155.1, xxx.xxx.xxx.xxx",
  "url": "http://localhost:9080/anything/user/get"
}

Header values and the reported origin address vary by browser and network environment.

The upstream request headers should not include the APISIX session cookie, access token, ID token, or user-information header. Reload the page to verify that APISIX reuses the browser session without redirecting you to Auth0.

Next Steps​

You have now configured APISIX to authenticate browser requests with Auth0. To authorize requests from services without an end-user session, see Authorize M2M Requests with Auth0. See the openid-connect plugin reference for more configuration options.