This page describes how to secure your app with signed IAP headers. When configured, Identity-Aware Proxy (IAP) uses JSON Web Tokens (JWT) to make sure that a request to your app is authorized. This protects your app from the following kind of risks:
- IAP is accidentally disabled;
- Misconfigured firewalls;
- Access from within the project.
To properly secure your app, you must use signed headers for all app types.
Alternatively, if you have an App Engine standard environment app, the Users API can be used.
Note that Compute Engine and GKE health checks don't include JWT headers and IAP doesn't handle health checks. If your health check returns access errors, make sure that you have it configured correctly in the Google Cloud console and that your JWT header validation allows the health check path. For more information, see Create a health check exception.
Before you begin
To secure your app with signed headers, you'll need the following:
- An application you want users to connect to.
- A third-party JWT library for your language that supports
the
ES256
algorithm.
Securing your app with IAP headers
To secure your app with the IAP JWT, verify the header,
payload, and signature of the JWT. The JWT is in the HTTP request header
x-goog-iap-jwt-assertion
. If an attacker bypasses IAP, they
can forge the IAP unsigned identity headers,
x-goog-authenticated-user-{email,id}
. The IAP JWT provides
a more secure alternative.
Signed headers provide secondary security in case someone bypasses
IAP. Note that when IAP is turned on, it
strips the x-goog-*
headers provided by the client when the request goes
through the IAP serving infrastructure.
Verifying the JWT header
Verify that the JWT's header conforms to the following constraints:
JWT Header Claims | ||
---|---|---|
alg |
Algorithm | ES256 |
kid |
Key ID |
Must correspond to one of the public keys listed in the
IAP key file, available in two different formats:
https://www.gstatic.com/iap/verify/public_key
and
https://www.gstatic.com/iap/verify/public_key-jwk
|
Make sure that the JWT was signed by the private key that corresponds to
the token's kid
claim. To do this, first grab the public key from one of two places:
https://www.gstatic.com/iap/verify/public_key
. This URL contains a JSON dictionary that maps thekid
claims to the public key values.https://www.gstatic.com/iap/verify/public_key-jwk
. This URL contains the IAP public keys in JWK format.
Once you have the public key, use a JWT library to verify the signature.
Verifying the JWT payload
Verify the JWT's payload conforms to the following constraints:
JWT Payload Claims | ||
---|---|---|
exp |
Expiration time | Must be in the future. The time is measured in seconds since the UNIX epoch. Allow 30 seconds for skew. The maximum lifetime of a token is 10 minutes + 2 * skew. |
iat |
Issued-at time | Must be in the past. The time is measured in seconds since the UNIX epoch. Allow 30 seconds for skew. |
aud |
Audience |
Must be a string with the following values:
|
iss |
Issuer |
Must be https://cloud.google.com/iap .
|
hd |
Account domain |
If an account belongs to a hosted domain, the
hd claim is provided to differentiate the
domain the account is associated with.
|
google |
Google claim |
If one or more access levels
apply to the request, their names are stored within the google
claim's JSON object, under the access_levels key, as an array
of strings.
When you specify a device policy and the Org has access to the device data, the |
You can get the values for the aud
string mentioned above by accessing the
Google Cloud console, or you can use the gcloud command-line tool.
To get aud
string values from the Google Cloud console, go to the
Identity-Aware Proxy settings
for your project, click More next to the Load Balancer resource, and then
select Signed Header JWT Audience. The Signed Header JWT dialog that
appears displays the aud
claim for the selected resource.
If you want to use the gcloud CLI
gcloud command-line tool to get the aud
string values, you'll need to know
the project ID. You can find the project ID on the
Google Cloud console
Project info card, then run the specified commands below for each value.
Project number
To get your project number using the gcloud command-line tool, run the following command:
gcloud projects describe PROJECT_ID
The command returns output like the following:
createTime: '2016-10-13T16:44:28.170Z' lifecycleState: ACTIVE name: project_name parent: id: '433637338589' type: organization projectId: PROJECT_ID projectNumber: 'PROJECT_NUMBER'
Service ID
To get your service ID using the gcloud command-line tool, run the following command:
gcloud compute backend-services describe SERVICE_NAME --project=PROJECT_ID --global
The command returns output like the following:
affinityCookieTtlSec: 0 backends: - balancingMode: UTILIZATION capacityScaler: 1.0 group: https://www.googleapis.com/compute/v1/projects/project_name/regions/us-central1/instanceGroups/my-group connectionDraining: drainingTimeoutSec: 0 creationTimestamp: '2017-04-03T14:01:35.687-07:00' description: '' enableCDN: false fingerprint: zaOnO4k56Cw= healthChecks: - https://www.googleapis.com/compute/v1/projects/project_name/global/httpsHealthChecks/my-hc id: 'SERVICE_ID' kind: compute#backendService loadBalancingScheme: EXTERNAL name: my-service port: 8443 portName: https protocol: HTTPS selfLink: https://www.googleapis.com/compute/v1/projects/project_name/global/backendServices/my-service sessionAffinity: NONE timeoutSec: 3610
Retrieving the user identity
If all of the above verifications are successful, retrieve the user identity. The ID token's payload contains the following user information:
ID Token Payload User Identity | ||
---|---|---|
sub |
Subject |
The unique, stable identifier for the user. Use this value instead of the
x-goog-authenticated-user-id header.
|
email |
User email | User email address.
|
Here is some sample code to secure an app with signed IAP headers:
C#
Go
Java
Node.js
PHP
Python
Ruby
Testing your validation code
If you visit your app using the
secure_token_test
query parameters,
IAP will include an invalid JWT. Use this to make sure your
JWT-validation logic is handling all of the various failure cases, and to see
how your app behaves when it receives an invalid JWT.
Creating a health check exception
As mentioned previously, Compute Engine and GKE health checks don't use JWT headers and IAP doesn't handle health checks. You'll need to configure your health check and app to allow the health check access.
Configuring the health check
If you haven't already set a path for your health check, use the Google Cloud console to set a non-sensitive path for the health check. Make sure this path isn't shared by any other resource.
- Go to the Google Cloud console
Health checks page.
Go to the Health checks page - Click the health check you're using for your app, then click Edit.
- Under Request path add a non-sensitive path name. This specifies the
URL path that Google Cloud uses when sending health check requests.
If omitted, the health check request is sent to
/
. - Click Save.
Configuring the JWT validation
In your code that calls the JWT validation routine, add a condition to serve an 200 HTTP status for your health check request path. For example:
if HttpRequest.path_info = '/HEALTH_CHECK_REQUEST_PATH' return HttpResponse(status=200) else VALIDATION_FUNCTION
JWTs for external identities
If you're using IAP with external identities, IAP will still issue a signed JWT on every authenticated request, just as it does with Google identities. However, there are a few differences.
Provider information
When using external identities, the JWT payload will contain a claim
named gcip
. This claim contains information about the user, such as their
email and photo URL, as well as any additional provider-specific attributes.
The following is an example of a JWT for a user who logged in with Facebook:
"gcip": '{
"auth_time": 1553219869,
"email": "[email protected]",
"email_verified": false,
"firebase": {
"identities": {
"email": [
"[email protected]"
],
"facebook.com": [
"1234567890"
]
},
"sign_in_provider": "facebook.com",
},
"name": "Facebook User",
"picture: "https://graph.facebook.com/1234567890/picture",
"sub": "gZG0yELPypZElTmAT9I55prjHg63"
}',
The email
and sub
fields
If a user was authenticated by Identity Platform, the email
and sub
fields of the JWT will be prefixed with the Identity Platform token issuer
and the tenant ID used (if any). For example:
"email": "securetoken.google.com/PROJECT-ID/TENANT-ID:[email protected]", "sub": "securetoken.google.com/PROJECT-ID/TENANT-ID:gZG0yELPypZElTmAT9I55prjHg63"
Controlling access with sign_in_attributes
IAM isn't supported for use with external identities, but
you can use claims embedded in the sign_in_attributes
field to control access
instead. For example, consider a user signed in using a SAML provider:
{
"aud": "/projects/project_number/apps/my_project_id",
"gcip": '{
"auth_time": 1553219869,
"email": "[email protected]",
"email_verified": true,
"firebase": {
"identities": {
"email": [
"[email protected]"
],
"saml.myProvider": [
"[email protected]"
]
},
"sign_in_attributes": {
"firstname": "John",
"group": "test group",
"role": "admin",
"lastname": "Doe"
},
"sign_in_provider": "saml.myProvider",
"tenant": "my_tenant_id"
},
"sub": "gZG0yELPypZElTmAT9I55prjHg63"
}',
"email": "securetoken.google.com/my_project_id/my_tenant_id:[email protected]",
"exp": 1553220470,
"iat": 1553219870,
"iss": "https://cloud.google.com/iap",
"sub": "securetoken.google.com/my_project_id/my_tenant_id:gZG0yELPypZElTmAT9I55prjHg63"
}
You could add logic to your application similar to the code below to restrict access to users with a valid role:
const gcipClaims = JSON.parse(decodedIapJwtClaims.gcip);
if (gcipClaims &&
gcipClaims.firebase &&
gcipClaims.firebase.sign_in_attributes &&
gcipClaims.firebase.sign_in_attribute.role === 'admin') {
// Allow access to admin restricted resource.
} else {
// Block access.
}
Additional user attributes from Identity Platform SAML and OIDC providers
can be accessed using the gcipClaims.gcip.firebase.sign_in_attributes
nested
claim.
IdP claims size limitations
After a user signs in with Identity Platform, the additional user attributes will be propagated to the stateless Identity Platform ID token payload which will be securely passed to IAP. IAP will then issue its own stateless opaque cookie which also contains the same claims. IAP will generate the signed JWT header based on the cookie content.
As a result, if a session is initiated with a large number of claims, it might exceed the maximum allowed cookie size which is typically ~4KB in most browsers. This will cause the sign-in operation to fail.
You should ensure that only the necessary claims are propagated in the IdP SAML or OIDC attributes. Another option is to use blocking functions to filter out claims that are not required for the authorization check.
const gcipCloudFunctions = require('gcip-cloud-functions');
const authFunctions = new gcipCloudFunctions.Auth().functions();
// This function runs before any sign-in operation.
exports.beforeSignIn = authFunctions.beforeSignInHandler((user, context) => {
if (context.credential &&
context.credential.providerId === 'saml.my-provider') {
// Get the original claims.
const claims = context.credential.claims;
// Define this function to filter out the unnecessary claims.
claims.groups = keepNeededClaims(claims.groups);
// Return only the needed claims. The claims will be propagated to the token
// payload.
return {
sessionClaims: claims,
};
}
});