Configure OIDC single sign-on in an ASM gateway - Alibaba Cloud Service Mesh

When multiple applications share a Service Mesh (ASM) ingress gateway, each application typically implements its own authentication logic -- duplicating effort and increasing security risk. OpenID Connect (OIDC), an identity layer built on OAuth 2.0, enables single sign-on (SSO) at the gateway level: users log in once, and the gateway forwards a verified JSON Web Token (JWT) to every backend application without any code changes.

How it works

A user sends a request to the ingress gateway.
The gateway checks for a valid session cookie. If none exists, it redirects the user to the identity provider (IdP) login page.
After authentication, the IdP redirects the user back to the gateway callback URL (/oauth2/callback) with an authorization code.
The gateway exchanges the code for tokens, sets a session cookie, and forwards the request to the backend with a JWT in the Authorization header.
The backend reads user identity from the JWT payload -- no direct call to the IdP is needed.

Prerequisites

Before you begin, make sure that you have:

An application deployed in the ASM instance. For more information, see Deploy applications in clusters associated with ASM instances
Automatic sidecar proxy injection enabled for the target namespaces. For more information, see Configure sidecar proxy injection policies
An ingress gateway created in the ASM instance, with its IP address noted. For more information, see Create an ingress gateway and Substep 1 of Step 3 in Use Istio resources to route traffic to different versions of a service
An IdP configured. For more information, see Step 1 and Step 2 in Integrate Alibaba Cloud IDaaS with ASM to implement single sign-on

After the IdP is configured, collect the following values for the OIDC configuration:

redirect URI:   http://<ingress-gateway-ip>/oauth2/callback
issuer URL:     https://eiam-api-cn-hangzhou.aliyuncs.com/v2/<idaas-instance-id>/app_<app-id>/oidc
client ID:      <your-client-id>
client secret:  <your-client-secret>

Important

The redirect URI must exactly match the callback URL registered with your IdP. A mismatch causes authentication failures because the IdP rejects the callback request.

Note

The following procedure uses Alibaba Cloud IDentity as a Service (IDaaS) as the IdP. If you use a self-managed OIDC IdP such as Keycloak, see Integrate Keycloak with ASM to implement single sign-on.

Configure OIDC settings

Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of the target ASM instance. In the left-side navigation pane, choose ASM Gateways > Ingress Gateway.
On the Ingress Gateway page, click the target ingress gateway. In the left-side navigation pane, choose Gateway Security > OIDC Single Sign-On.

In the OIDC Config step, turn on Enable gateway OIDC Single Sign-On and configure the following parameters.

Note

To discover available endpoints and supported scopes, query your IdP's well-known configuration endpoint:

curl <your-issuer-url>/.well-known/openid-configuration | jq

Parameter	Description
Redirect address	The protocol and address for OIDC callbacks. In this example, select Use ingressgateway IP address and http.
Callback Address	The full URL to which the IdP redirects users after authentication.
OIDC Issuer URL	The URL used to identify and authenticate the OIDC issuer. The gateway derives the discovery endpoint from this URL to fetch the IdP's public keys and endpoints.
Client ID	The client ID assigned by the IdP when you registered the application.
Client Secret	The client secret assigned by the IdP.
Cookie Secret	A seed string for secure session cookies, which can be Base64-encoded.
Cookie Expire	How long the session cookie remains valid. Set to `0` for cookies that do not expire.
Cookie refresh interval	How often the session cookie is refreshed. Set to `0` to disable automatic refresh.
Scopes	The OIDC scopes to request from the IdP (for example, `openid`, `email`, `profile`). The IdP must support the specified scopes.

OIDC configuration

Click Next.

Configure path matching rules

In the Matching Rule step, configure which request paths require OIDC authentication. In this example, select Auth If Matched and set the path to /productpage. Requests to /productpage are redirected to the IdP for authentication, while requests to other paths pass through without OIDC checks.

Parameter	Description
Match Mode	Controls how the path rule is applied. Valid values: Auth If Matched -- requests to the specified path require authentication. Bypass Auth If Matched -- requests to the specified path skip authentication.
Add Match Rule	Turn on the Path switch and specify the path. In this example, set the path to `/productpage`.

Click Submit. The Complete step confirms that OIDC-based SSO is configured. The page displays the native Istio security resources generated by the wizard. Click YAML to review the resource configurations.

Verify the configuration

Open a browser and go to http://<ingress-gateway-ip>/productpage. Replace <ingress-gateway-ip> with the IP address of your ingress gateway. If the configuration is correct, the browser redirects to the IdP login page. After you authenticate, the browser redirects back and displays the application page.

Set up logout

A complete SSO logout requires two actions: clearing the gateway session cookie and terminating the IdP session.

Action	How to trigger
Clear the gateway session cookie	Visit `http://<ingress-gateway-ip>/oauth2/sign_out`. The gateway clears the session cookie automatically.
End the IdP session	Visit the logout URI exposed by your IdP.

Single-step logout (ASM v1.18.147 and later)

ASM v1.18.147 and later lets you combine both actions by configuring an IdP logout endpoint on the OIDC configuration page:

Enter the IdP logout endpoint URL on the OIDC configuration page.
Add a matching rule that sets the /oauth2/sign_out path to Bypass Auth If Matched so the sign-out path does not require authentication.

After this setup, visiting /oauth2/sign_out clears the session cookie and redirects to the IdP logout endpoint in a single step. For more information about IDaaS single logout, see SLO.

FAQ

Does my application need to handle OIDC authentication?

No. The ingress gateway handles the entire OIDC flow. Your application receives each request with an Authorization header containing a JWT issued by the IdP. The gateway has already validated this token, so your application can parse it directly to extract user information such as sub, email, or custom claims -- no additional call to the IdP is needed.

What is the session cookie used for?

The gateway uses the session cookie to track the authentication state of each user. Your application can safely ignore this cookie. To access user identity, read the JWT from the Authorization header instead.

How do I get extended user attributes from the IdP?

No additional ASM configuration is needed. Extended attributes depend on your IdP implementation. For Alibaba Cloud IDaaS, see Rules for OIDC id_token Extended Fields.

References

General Config, Configure SSO, OIDC SSO Configuration, and Rules for OIDC id_token Extended Fields in the IDaaS documentation
SLO -- Global logout for Alibaba Cloud IDaaS