Skip to main content
API7.ai Logo
Version: 3.18.0

Set Up SSO with Google

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.

Google Identity provides authentication services for applications that use Google Accounts. Google Auth Platform manages the application's consent-screen branding, audience, test users, and OAuth clients. In this integration, Apache APISIX delegates browser authentication to Google before proxying requests to an upstream service.

The guide shows how to configure Google Auth Platform and a web application client, then configure APISIX 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 Google. After successful authentication, APISIX exchanges the authorization code for tokens, creates a browser session, and resumes the original request.

Prerequisite(s)​

Configure Google​

Configure Google Auth Platform for external test users, then create a web application client for APISIX.

Configure the App and Audience​

Sign in to the Google Cloud console and select the project that will own the OAuth configuration. Open Google Auth Platform → Overview and configure the application:

  1. Select Get started.
  2. Enter APISIX Authorization Code as the app name and select a user support email.
  3. Select Next.
  4. Select External as the audience and select Next.
  5. Enter a developer contact email and select Next.
  6. Accept the Google API Services User Data Policy and select Continue.
  7. Select Create.

The application starts in Testing status. In this status, only accounts added as test users can complete the authentication flow.

Add a Google Account for testing:

  1. Select Audience → Add users.
  2. Enter the account's email address.
  3. Select Save.

For a production application, configure the required branding information and review Google's publishing and verification requirements before changing the application to In production.

Create an OAuth Client​

Create the web application client that Google uses to identify APISIX:

  1. Select Clients → Create client.
  2. Select Web application as the application type.
  3. Enter APISIX Authorization Code as the client name.
  4. Under Authorized redirect URIs, select Add URI and enter http://localhost:9080/anything/user/callback.
  5. Select Create.
Create the Google OAuth web client with the APISIX redirect URI

Google displays the client ID and client secret after creating the client. Copy both values before closing the dialog. The client ID remains available on the client's details page, but Google does not display or allow downloading the client secret again. If the secret is lost, add a new client secret.

In production, use an HTTPS redirection endpoint that users can reach and register that exact URI in the OAuth client.

Save the OIDC Configuration​

Save the client ID, client secret, and Google discovery URL to environment variables, replacing the examples:

export GOOGLE_CLIENT_ID=replace-with-your-client-id
export GOOGLE_CLIENT_SECRET=replace-with-your-client-secret
export GOOGLE_DISCOVERY=https://accounts.google.com/.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/google-sso" -X PUT \
  --data-binary @- <<EOF
{
  "uri": "/anything/user/*",
  "plugins": {
    "openid-connect": {
      "client_id": "$GOOGLE_CLIENT_ID",
      "client_secret": "$GOOGLE_CLIENT_SECRET",
      "discovery": "$GOOGLE_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 Google's OIDC discovery document.

❷ redirect_uri: URI where Google returns the browser after authentication. It must match the authorized redirect URI configured for the OAuth client.

❸ 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 Google, where you can select or sign in to a test account and review the requested profile information.

After you continue, Google 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 Google.

Next Steps​

You have now configured APISIX to authenticate browser requests with Google. See the openid-connect plugin reference for more configuration options.