Configuring Cloud Service Mesh user authentication

If you have theTRAFFIC_DIRECTORcontrol plane implementation thenthis feature is only supported by allow-list. Please contact support to requestthis feature be allowlisted for your organization

Cloud Service Mesh user authentication is an integrated solution for browser-basedend-user authentication and access control to your deployed workloads. It letsyou integrate with existing Identity Providers (IDP) for user authentication anduses Istio APIs and authorization policies for access management. It is auser-friendly alternative to Istio JSON Web Token (JWT) authentication.

A typical use-case is when an organization uses Cloud Service Mesh to host aweb application for its workforce to access via a web browser. In addition, theorganization needs to use their existing identity provider to manage useridentities. Cloud Service Mesh user authentication makes it easy for users toauthenticate using a standard web-based OpenID Connect (OIDC) login and consentflow. When the user authenticates, Cloud Service Mesh enforces Istioauthorization policies, and on successful authorization, it transmits theidentity to workloads in a secure credential format.

How it works

Cloud Service Mesh user authentication introduces a new component,authservice.This component integrates with the Envoy-based ingress as an externalauthorization service that intercepts all the incoming requests forauthentication.authservice implements the client-side of the OIDC protocoland enables user access to applications via a browser, where users complete aninteractive authentication and consent flow to establish a short-lived session.authservice implements industry standard protocols to integrate with anyidentity provider that can act as a OIDC authorization server. When the user isauthenticated, the principal information is encapsulated in anRCToken in JWTformat, signed byauthservice which it forwards to the Istio authorizationlayer in the ingress. This model provides perimeter access control for trafficinto the mesh. If the user is authorized to access a resource, this RCToken isalso forwarded to the microservices to obtain principal information and enforcefine-grained access control.

The following diagram shows the location ofauthservice in the mesh and how itrelates to the other parts of the mesh, such as the ingress, workloads, user'sbrowser, and any existing IDP.

Administrators can installauthservice as an add-on over a Cloud Service Meshinstallation. When installed,authservice reads the OIDC endpointconfiguration and other associated settings defined in theUserAuth customresource. The administrator can use Cloud Service MeshExternalAuthorization APIsto configureauth_server as a filter on the ingress.

Install the user authentication service

The following steps explain how to configure theauthservice.

Prerequisites

• Install required tools
• Downloadasmcli
• Grant cluster admin permissions
• Validate your project and cluster

• If you are using managed Cloud Service Mesh on a private cluster, then ensure thecluster is capable of sending egress traffic to the IDP.

Additionally, ensure that you meet the prerequisites by using the followingsteps.

Customize the installation user authentication overlay

To install the user authentication service, you must customize the Cloud Service Meshinstallation to add a mesh-level external authorization provider. The stepsrequired depend on whether you are using managed or in-cluster Cloud Service Mesh.

Prepare the OIDC client configuration

Set your OIDC client configuration by using the following steps. This guide usesGoogle as an IDP, but you can use any IDP that supports OIDC authentication.

1. In the Google Cloud console, go toAPI & Services >Credentials.

   Go to Credentials

2. Go toCreate Credentials, then chooseOAuth client ID. If required,set yourOAuth consent screen options, then configure the followingoptions:

   • SetApplication type toWeb application.
   • SetAuthorized redirect URI tohttps://REDIRECT_HOST/REDIRECT_PATH.For example, for localhost you could set tohttps://localhost:8443/_gcp_asm_authenticate.

   Then, clickSave.

3. In addition, save your OIDC client configuration to use later.

   exportOIDC_CLIENT_ID=CLIENT_IDexportOIDC_CLIENT_SECRET=CLIENT_SECRETexportOIDC_ISSUER_URI=ISSUER_URIexportOIDC_REDIRECT_HOST=REDIRECT_HOSTexportOIDC_REDIRECT_PATH=REDIRECT_PATH

Get thekpt packages

Use the following steps to install the recommendedauthservice configurationfrom thepublic repository. Thesecommands retrieve the latestauthservice container and start it as a Pod intheasm-user-auth namespace. It also configures the ingress to intercept allrequests.

Get the kpt package:

kptpkggethttps://github.com/GoogleCloudPlatform/asm-user-auth.git/@v1.2.5.cdasm-user-auth/

Set the redirection URL and secret for ingress gateway

OAuth2 requires a redirection URL hosted on an HTTPS-protected endpoint. Thesecommands are for example purposes and simplify setup by generating a self-signedcertificate for the Istio ingress gateway.

1. Prepare the session encryption key with following format or use the samplefrom the pkg, which you can view bycat ./samples/cookie_encryption_key.json.

   {"keys":[{"kty":"oct","kid":"key-0","K":"YOUR_KEY","useAfter":1612813735}]}

   You can generate a test AES key with following command:

   opensslenc-aes-256-cbc-kmycustomkey-P-mdsha1|grepkey

2. Prepare the RCToken signing key with following format or use the samplefrom the pkg, which you can view bycat ./samples/rctoken_signing_key.json.

   {"keys":[{"kty":"RSA","kid":"rsa-signing-key","K":"YOUR_KEY",#kcontainsaBase64encodedPEMformatRSAsigningkey."useAfter":1612813735#unixtimestamp}]}

   You can generate a test 512-bit RSA private key with following command:

   opensslgenpkey-algorithmRSA-outrsa_private.pem-pkeyoptrsa_keygen_bits:512

3. Create the kubernetes secret, whichauthservice will mount into its ownfile system.

   Important: In a production environment, generate your own keys to populatethe JSON file instead.

   kubectlcreatesecretgenericsecret-key\--from-file="session_cookie.key"="./samples/cookie_encryption_key.json"\--from-file="rctoken.key"="./samples/rctoken_signing_key.json"\--namespace=asm-user-auth

Deploy the user authentication service

The following commands create the user authentication service and deployment intheasm-user-auth namespace.

Set the necessary values for User Auth configuration. The client ID andsecret are stored as Kubernetes secrets, so we use Base64 to encode them.Please visitpublic repositoryto view all available setters.

kptfnevalpkg--imagegcr.io/kpt-fn/apply-setters:v0.2--truncate-output=false--\client-id="$(echo-n${OIDC_CLIENT_ID}|base64-w0)"\client-secret="$(echo-n${OIDC_CLIENT_SECRET}|base64-w0)"\issuer-uri="${OIDC_ISSUER_URI}"\redirect-host="${OIDC_REDIRECT_HOST}"\redirect-path="${OIDC_REDIRECT_PATH}"

Apply thekpt package:

# Remove the potential alpha version CRD if exists.kubectldeletecrduserauthconfigs.security.anthos.iokubectlapply-f./pkg/asm_user_auth_config_v1beta1.yamlkubectlapply-f./pkg

Theauthservice consumes theUserAuthConfig CRD to provide end userauthentication.UserAuthConfig is configurable in the run time, and you canupdate it to change theauthservice behavior and configure it with endpointsfor any OIDC authorization server.

You can view the file bycat pkg/user_auth_config.yaml, it contains these fields:

apiVersion:security.anthos.io/v1beta1kind:UserAuthConfigmetadata:name:user-auth-confignamespace:asm-user-authspec:authentication:oidc:certificateAuthorityData:""# kpt-set: ${ca-cert}issuerURI:"<yourissueruri>"# kpt-set: ${issuer-uri}proxy:""# kpt-set: ${proxy}oauthCredentialsSecret:name:"oauth-secret"# kpt-set: ${secret-name}namespace:"asm-user-auth"# kpt-set: ${secret-namespace}redirectURIHost:""# kpt-set: ${redirect-host}redirectURIPath:"/_gcp_asm_authenticate"# kpt-set: ${redirect-path}scopes:""# kpt-set: ${scopes}groupsClaim:""# kpt-set: ${groups}outputJWTAudience:"test_audience"# kpt-set: ${jwt-audience}

Seeuser authentication configuration detailsfor detailed descriptions of theuser_auth_config.yaml fields.

Configure API Request Identifiers

API request identifiers are a set ofCommon Expression Language (CEL)expressions used by Cloud Service Mesh user authentication to identify APIrequests. By defining these identifiers, you enable Cloud Service Mesh userauthentication to handle API request authentication failures semantically.

Specifically, when you provide CEL expressions that identify your API requests,you allow Cloud Service Mesh user authentication to fail unauthenticated APIrequests with a 401-Unauthorized status code. This is crucial for clients likeCLIs and service accounts, which expect this status code for unauthenticated APIrequests.

Without API request identifiers, Cloud Service Mesh user authentication willredirect all unauthenticated requests to the configured OpenID Connect (OIDC) provider,returning a 302-Found status code. This redirect behavior is generally undesirablefor API requests, which expect a 401-Unauthorized on failure.

To define your API request identifiers, add anapiRequestIdentifier section toyourUserAuthConfig CR. This allows adding multiple CEL expressions. If multipleCEL expressions are provided, a request is considered an API request if it matchesat least one of them.

The following example shows how to designate as an API request: any requestcontaining the headerexample-api-header, any request directed to the hostapi.example.com, or any request targeting a path under/v1/api/.

apiVersion:security.anthos.io/v1beta1kind:UserAuthConfigmetadata:name:user-auth-confignamespace:asm-user-authspec:authentication:oidc:certificateAuthorityData:""# kpt-set: ${ca-cert}issuerURI:"<yourissueruri>"# kpt-set: ${issuer-uri}proxy:""# kpt-set: ${proxy}oauthCredentialsSecret:name:"oauth-secret"# kpt-set: ${secret-name}namespace:"asm-user-auth"# kpt-set: ${secret-namespace}redirectURIHost:""# kpt-set: ${redirect-host}redirectURIPath:"/_gcp_asm_authenticate"# kpt-set: ${redirect-path}scopes:""# kpt-set: ${scopes}groupsClaim:""# kpt-set: ${groups}outputJWTAudience:"test_audience"# kpt-set: ${jwt-audience}apiRequestIdentifier:name:"api-request-identifiers"expressions:-"'example-api-header'inhttp_request.headers"-"http_request.host==api.example.com"-"matches(http_request.path,'/v1/api/(.*)')"# other expressions go here

"'x-api-key'inhttp_request.headers"

"'x-api-key'inhttp_request.headers &&http_request.headers['x-api-key'].values==['example-value']"

"http_request.host==api.example.com"

"http_request.path==/api/query"

"matches(http_request.path,'/api/(.*)')"

Cloud Service Mesh user authentication uses aCUSTOMtyped authorization policy to trigger the OIDC flow.

After you haveinstalled the Istio gateway,configure it to serve HTTPS traffic using the TLS certificateuserauth-tls-certyou created above. Below is thepkg/gateway.yaml configuration that you justinstalled.

apiVersion:networking.istio.io/v1beta1kind:Gatewaymetadata:name:userauthnamespace:asm-user-authspec:selector:istio:ingressgatewayservers:-hosts:-'*'port:name:httpsnumber:443protocol:HTTPStls:mode:SIMPLEcredentialName:userauth-tls-cert---# This ensures the OIDC endpoint has at least some route defined.apiVersion:networking.istio.io/v1beta1kind:VirtualServicemetadata:name:userauth-oidcnamespace:asm-user-authspec:gateways:-userauthhosts:-'*'http:-match:-uri:prefix:/status-uri:prefix:"your-oidc-redirect-path"name:user-auth-routeroute:-destination:host:authserviceport:number:10004

1. Labeldefault namespace to enableistio-proxy auto injection fordeployments.

   kubectllabelnamespacedefaultistio.io/rev=REVISION--overwrite

2. Deployhttpbin todefault namespace.

   kubectlapply-fhttps://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml-ndefault

3. Updatehttpbin to use this gateway to serve HTTPS traffic, and use portforwarding to access the application locally:

   kubectlapply-f./samples/httpbin-route.yaml-ndefaultkubectlport-forwardservice/istio-ingressgateway8443:443-nasm-user-auth

   apiVersion:networking.istio.io/v1alpha3kind:VirtualServicemetadata:name:httpbinnamespace:defaultspec:gateways:-asm-user-auth/userauthhosts:-'*'http:-match:-uri:prefix:/ip-uri:prefix:/headersname:httpbin-routesroute:-destination:host:httpbin.default.svc.cluster.localport:number:8000

   The ingress gateway on port 8443 will be forwarded tolocalhost to makethe application accessible locally.

4. Deploy thesamples/rctoken-authz.yaml to enable RequestAuthentication andAuthorizationPolicy to verify the RCToken for the requests.

   kubectlapply-f./samples/rctoken-authz.yaml-nasm-user-auth

   Examplesamples/rctoken-authz.yaml:

   apiVersion:security.istio.io/v1beta1kind:RequestAuthenticationmetadata:name:require-rc-tokenspec:selector:matchLabels:istio:ingressgatewayjwtRules:-issuer:"authservice.asm-user-auth.svc.cluster.local"audiences:-"test_audience"jwksUri:"http://authservice.asm-user-auth.svc.cluster.local:10004/_gcp_user_auth/jwks"fromHeaders:-name:X-ASM-RCTOKENforwardOriginalToken:true---apiVersion:security.istio.io/v1beta1kind:AuthorizationPolicymetadata:name:require-rc-tokenspec:selector:matchLabels:istio:ingressgatewayaction:ALLOWrules:-when:-key:request.auth.claims[iss]values:-authservice.asm-user-auth.svc.cluster.local-key:request.auth.claims[aud]values:-test_audience

Verify user authentication

Thehttpbin serves two paths,/ip is publicly accessible and/headersrequires the end user to login via their configured IDP.

{"keys":[{"kty":"RSA","kid":"old-key","K":"...",#kcontainsaBase64encodedPEMformatRSAsigningkey."useAfter":1612813735,#unixtimestamp}{"kty":"RSA","kid":"new-key","K":"...",#kcontainsaBase64encodedPEMformatRSAsigningkey."useAfter":1712813735,#unixtimestamp}]}

apiVersion:networking.istio.io/v1beta1kind:DestinationRulemetadata:name:authservice-fail-overnamespace:asm-user-authspec:host:authservice.asm-user-auth.svc.cluster.localtrafficPolicy:loadBalancer:localityLbSetting:enabled:truefailover:-from:us-eastto:us-west-from:us-westto:us-east

spec:authentication:oidc:attributeMapping:aud_copy:assertion.auddecision:'assertion.sub.startsWith("123")?"success":"fail"'

"attributes":{"aud_copy":"foo.googleusercontent.com","decision":"success"}

1. Install the user-auth packages again as it contains the updated binary for new user-auth version:

   kptpkggethttps://github.com/GoogleCloudPlatform/asm-user-auth.git/@v1.2.5.cdasm-user-auth/

2. Save your OIDC client configuration:

   exportOIDC_CLIENT_ID=CLIENT_IDexportOIDC_CLIENT_SECRET=CLIENT_SECRETexportOIDC_ISSUER_URI=ISSUER_URIexportOIDC_REDIRECT_HOST=REDIRECT_HOSTexportOIDC_REDIRECT_PATH=REDIRECT_PATH

3. Deploy the user authentication serviceto upgrade to a new version.

User authentication configuration details

The following table describes each field in the CRD:

Troubleshoot

1. Network accessibility to IDP.

   Possible log:error: TLS handshake failed..

   Verify by executingcurl from the ephemeral container attached to theistio-proxy to callIDP issuer URI. For example, seeCollecting Cloud Service Meshlogs.

   If you're unable to connect, check the firewall rules orother network configurations for the cluster.

2. Root CA certificate.

   Possible log:error: The server's TLS certificate did not match expectations.orerror: TLS handshake failed..

   Make sure thecertificateAuthorityData holds the correct root CA certificate.When there is no HTTPS proxy terminating HTTPS traffic, this should hold the rootCA certificate for the IDP. If there is one, this should hold the proxy's instead.

3. Redirect path configuration.

   Possible observation: receive 404 error page during OIDC authentication flow.

   User Auth returns the "Set-Cookie" header without using the path attribute,which by default the browser uses the directory of the request url as thecookie path (scope of the cookie related to path). So we recommend to notinclude "/" in the redirect path unless you are intended.

4. The sidecar is not able to fetch jwksUri.

   In some scenarios, asidecar restriction could lead to failure of fetching jwksUri. If the namespace isnot present using a wildcard (for example,./* oristio-system/*) thenthis will not work. You must manually add their namespace in the egresssidecar.

FAQs

1. How do I upgrade Cloud Service Mesh with User Auth enabled?

   Follow theCloud Service Mesh upgradeprocess and specify the overlay file by adding--custom_overlay user-auth-overlay.yaml on the command line toasmcli install.

2. How much resources should we provision for theauthservice? And how manyrequests per second can it handle?

   By default,authservice is configured with 2.0 vCPU, 256Mi memory. Undersuch configuration,authservice is able to handle 500 requests per second.To handle larger amounts of requests, you should provisionmore CPU,which is roughly proportionally to its requests handling capacity. You canalso configure multiple replicas of the authservice to increase thehorizontal scalability.