Programmatic authentication

This page describes how to authenticate to an Identity-Aware Proxy (IAP)-secured resource from a user account or a service account.

• A user account belongs to an individual user. You authenticate a user account when your application requires access to IAP-secured resources on a user's behalf. For more information, see User accounts.

• A service account belongs to an application instead of an individual user. You authenticate a service account when you want to allow an application to access your IAP-secured resources. For more information, see Service accounts.

Before you begin

Before you begin, you'll need the following:

• A IAP-secured application to which you want to programmatically connect using a developer account, service account, or mobile app credentials.

Authenticating a user account

You can enable user access to your app from a desktop or mobile app to allow a program to interact with a IAP-secured resource.

Authenticating from a mobile app

1. Create an OAuth 2.0 client ID for your mobile app in the same project as the IAP-secured resource:
   1. Go to the Credentials page.
      Go to the Credentials page
   2. Select the project with the IAP-secured resource.
   3. Click Create credentials, then select OAuth Client ID.
   4. Select the Application type for which you want to create credentials.
   5. Add a Name and Restrictions if appropriate, then click Create.
2. On the OAuth client window that appears, note the Client ID for the IAP-secured resource you want to connect to.
3. Get an ID token for the IAP-secured client ID:
   • Android: Use the Google Sign-In API to request an OpenID Connect (OIDC) token. Set the requestIdToken client ID to the client ID for the resource you're connecting to.
   • iOS: Use Google Sign-In to get an ID token. Set serverClientID to the client ID for the resource you're connecting to.
4. Include the ID token in an Authorization: Bearer header to make the authenticated request to the IAP-secured resource.

Authenticating from a desktop app

This section describes how to authenticate a user account from a desktop command line.

Setting up the client ID

To allow developers to access your application from the command line, you'll first need to create OAuth client ID credentials of type Desktop app:

1. Go to the Credentials page.
   Go to the Credentials page
2. Select the project with the IAP-secured resource.
3. Click Create credentials, then select OAuth Client ID.
4. Under Application type, select Desktop app, add a Name, then click Create.
5. On the OAuth client window that appears, note the client ID and client secret. You'll need to use these in a script to manage credentials or otherwise share with your developers.
6. On the Credentials window, your new Desktop app credentials appear along with the primary client ID that's used to access your application.

Signing in to the application

Each developer who wants to access a IAP-secured app will need to sign in first. You can package the process into a script, such as by using gcloud CLI. Following is an example using curl to sign in and generate a token that can be used to access the application:

1. Sign in to your account that has access to the Google Cloud resource.
2. Start a local server that can echo the incoming requests.

       $ nc -k -l 4444
       

   NOTE: The command uses the NetCat utility. You can use the utility of your choice.
3. Go to the following URI where DESKTOP_CLIENT_ID is the Desktop app client ID you created above:

   https://accounts.google.com/o/oauth2/v2/auth?client_id=DESKTOP_CLIENT_ID&response_type=code&scope=openid%20email&access_type=offline&redirect_uri=http://localhost:4444&cred_ref=true

4. In the local server output, look for the request parameters. You should see something like the following: GET /?code=$CODE&scope=email%20openid%20https://www.googleapis.com/auth/userinfo.email&hd=google.com&prompt=consent HTTP/1.1 copy the CODE to replace AUTH_CODE below along with the Desktop app client ID and secret you created above. IAP_CLIENT_ID is the primary client ID used to access your application:

   curl --verbose \
         --data client_id=DESKTOP_CLIENT_ID \
         --data client_secret=DESKTOP_CLIENT_SECRET \
         --data code=AUTH_CODE \
         --data audience=IAP_CLIENT_ID \
         --data redirect_uri=http://localhost:4444 \
         --data grant_type=authorization_code \
         https://oauth2.googleapis.com/token

   This code returns a JSON object with an id_token field that you can use to access the application.

Accessing the application

To access the app, use the id_token as follows:

curl --verbose --header 'Authorization: Bearer ID_TOKEN' URL

Refresh Token

You can use the refresh token generated during the sign-in flow to get new ID tokens. This is useful when the original ID token expires. Each ID token is valid for about one hour, during which time you can make multiple requests to a specific app.

The following is an example using curl to use the refresh token to get a new ID token. In the following example, REFRESH_TOKEN is the token from the sign-in flow. IAP_CLIENT_ID, DESKTOP_CLIENT_ID, and DESKTOP_CLIENT_SECRET are the same as used in the sign-in flow:

curl --verbose \
--data client_id=DESKTOP_CLIENT_ID \
--data client_secret=DESKTOP_CLIENT_SECRET \
--data refresh_token=REFRESH_TOKEN \
--data grant_type=refresh_token \
--data audience=IAP_CLIENT_ID \
https://oauth2.googleapis.com/token

This code returns a JSON object with a new id_token field that you can use to access the app.

Note: The refresh token workflow is not supported for access level policies. You must regenerate a new ID token using the full authentication flow.

Authenticating from a service account

Use an OpenID Connect (OIDC) token to authenticate a service account to a IAP-secured resource. Follow these steps to find your client ID:

1. Go to the IAP page.

2. Find the resource you want to access, then click  > Go to OAuth configuration.
   

3. On the page that appears, note the client ID. You can change the client ID for a backend service by using the gcloud compute backend-services update command.

   gcloud compute backend-services update BACKEND_SERVICE_NAME \
       --iap='enabled,oauth2-client-id=OAUTH_CLIENT_ID,oauth2-client-secret=OAUTH_CLIENT_SECRET'

   Replace the following:

   • BACKEND_SERVICE_NAME: The name of the backend service account.
   • OAUTH_CLIENT_ID: The new OAuth client ID.
   • OAUTH_CLIENT_SECRET: The new OAuth client secret.
   This is also useful if you want to use the same OAuth client for multiple backends.

You also need to add the service account to the access list for the IAP-secured project. The following code samples show how to obtain an OIDC token. No matter which one you choose, you need to include the token in an Authorization: Bearer header to make the authenticated request to the IAP-secured resource.

Note: Ensure that the generated ID token has an 'email' claim. This is a requirement for IAP.

Obtaining an OIDC token for the default service account

If you want to get an OIDC token for the default service account for Compute Engine, App Engine, or Cloud Run, you can use the following code sample to generate the token to access a IAP-secured resource:

C#

View on GitHub Feedback

using Google.Apis.Auth.OAuth2;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading;
using System.Threading.Tasks;

public class IAPClient
{
    /// <summary>
    /// Makes a request to a IAP secured application by first obtaining
    /// an OIDC token.
    /// </summary>
    /// <param name="iapClientId">The client ID observed on 
    /// https://console.cloud.google.com/apis/credentials. </param>
    /// <param name="uri">HTTP URI to fetch.</param>
    /// <param name="cancellationToken">The token to propagate operation cancel notifications.</param>
    /// <returns>The HTTP response message.</returns>
    public async Task<HttpResponseMessage> InvokeRequestAsync(
        string iapClientId, string uri, CancellationToken cancellationToken = default)
    {
        // Get the OidcToken.
        // You only need to do this once in your application
        // as long as you can keep a reference to the returned OidcToken.
        OidcToken oidcToken = await GetOidcTokenAsync(iapClientId, cancellationToken);

        // Before making an HTTP request, always obtain the string token from the OIDC token,
        // the OIDC token will refresh the string token if it expires.
        string token = await oidcToken.GetAccessTokenAsync(cancellationToken);

        // Include the OIDC token in an Authorization: Bearer header to 
        // IAP-secured resource
        // Note: Normally you would use an HttpClientFactory to build the httpClient.
        // For simplicity we are building the HttpClient directly.
        using HttpClient httpClient = new HttpClient();
        httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
        return await httpClient.GetAsync(uri, cancellationToken);
    }

    /// <summary>
    /// Obtains an OIDC token for authentication an IAP request.
    /// </summary>
    /// <param name="iapClientId">The client ID observed on 
    /// https://console.cloud.google.com/apis/credentials. </param>
    /// <param name="cancellationToken">The token to propagate operation cancel notifications.</param>
    /// <returns>The HTTP response message.</returns>
    public async Task<OidcToken> GetOidcTokenAsync(string iapClientId, CancellationToken cancellationToken)
    {
        // Obtain the application default credentials.
        GoogleCredential credential = await GoogleCredential.GetApplicationDefaultAsync(cancellationToken);

        // Request an OIDC token for the Cloud IAP-secured client ID.
       return await credential.GetOidcTokenAsync(OidcTokenOptions.FromTargetAudience(iapClientId), cancellationToken);
    }
}

Go

To authenticate to IAP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"net/http"

	"google.golang.org/api/idtoken"
)

// makeIAPRequest makes a request to an application protected by Identity-Aware
// Proxy with the given audience.
func makeIAPRequest(w io.Writer, request *http.Request, audience string) error {
	// request, err := http.NewRequest("GET", "http://example.com", nil)
	// audience := "IAP_CLIENT_ID.apps.googleusercontent.com"
	ctx := context.Background()

	// client is a http.Client that automatically adds an "Authorization" header
	// to any requests made.
	client, err := idtoken.NewClient(ctx, audience)
	if err != nil {
		return fmt.Errorf("idtoken.NewClient: %w", err)
	}

	response, err := client.Do(request)
	if err != nil {
		return fmt.Errorf("client.Do: %w", err)
	}
	defer response.Body.Close()
	if _, err := io.Copy(w, response.Body); err != nil {
		return fmt.Errorf("io.Copy: %w", err)
	}

	return nil
}

Java

View on GitHub Feedback

import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.auth.oauth2.IdTokenCredentials;
import com.google.auth.oauth2.IdTokenProvider;
import com.google.common.base.Preconditions;
import java.io.IOException;
import java.util.Collections;

public class BuildIapRequest {
  private static final String IAM_SCOPE = "https://www.googleapis.com/auth/iam";

  private static final HttpTransport httpTransport = new NetHttpTransport();

  private BuildIapRequest() {}

  private static IdTokenProvider getIdTokenProvider() throws IOException {
    GoogleCredentials credentials =
        GoogleCredentials.getApplicationDefault().createScoped(Collections.singleton(IAM_SCOPE));

    Preconditions.checkNotNull(credentials, "Expected to load credentials");
    Preconditions.checkState(
        credentials instanceof IdTokenProvider,
        String.format(
            "Expected credentials that can provide id tokens, got %s instead",
            credentials.getClass().getName()));

    return (IdTokenProvider) credentials;
  }

  /**
   * Clone request and add an IAP Bearer Authorization header with ID Token.
   *
   * @param request Request to add authorization header
   * @param iapClientId OAuth 2.0 client ID for IAP protected resource
   * @return Clone of request with Bearer style authorization header with ID Token.
   * @throws IOException exception creating ID Token
   */
  public static HttpRequest buildIapRequest(HttpRequest request, String iapClientId)
      throws IOException {

    IdTokenProvider idTokenProvider = getIdTokenProvider();
    IdTokenCredentials credentials =
        IdTokenCredentials.newBuilder()
            .setIdTokenProvider(idTokenProvider)
            .setTargetAudience(iapClientId)
            .build();

    HttpRequestInitializer httpRequestInitializer = new HttpCredentialsAdapter(credentials);

    return httpTransport
        .createRequestFactory(httpRequestInitializer)
        .buildRequest(request.getRequestMethod(), request.getUrl(), request.getContent());
  }
}

Node.js

View on GitHub Feedback

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const url = 'https://some.iap.url';
// const targetAudience = 'IAP_CLIENT_ID.apps.googleusercontent.com';

const {GoogleAuth} = require('google-auth-library');
const auth = new GoogleAuth();

async function request() {
  console.info(`request IAP ${url} with target audience ${targetAudience}`);
  const client = await auth.getIdTokenClient(targetAudience);
  const res = await client.request({url});
  console.info(res.data);
}

request().catch(err => {
  console.error(err.message);
  process.exitCode = 1;
});

PHP

To authenticate to IAP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

namespace Google\Cloud\Samples\Iap;

# Imports Auth libraries and Guzzle HTTP libraries.
use Google\Auth\ApplicationDefaultCredentials;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;

/**
 * Make a request to an application protected by Identity-Aware Proxy.
 *
 * @param string $url The Identity-Aware Proxy-protected URL to fetch.
 * @param string $clientId The client ID used by Identity-Aware Proxy.
 */
function make_iap_request($url, $clientId)
{
    // create middleware, using the client ID as the target audience for IAP
    $middleware = ApplicationDefaultCredentials::getIdTokenMiddleware($clientId);
    $stack = HandlerStack::create();
    $stack->push($middleware);

    // create the HTTP client
    $client = new Client([
        'handler' => $stack,
        'auth' => 'google_auth'
    ]);

    // make the request
    $response = $client->get($url);
    print('Printing out response body:');
    print($response->getBody());
}

Python

To authenticate to IAP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

from google.auth.transport.requests import Request
from google.oauth2 import id_token
import requests


def make_iap_request(url, client_id, method="GET", **kwargs):
    """Makes a request to an application protected by Identity-Aware Proxy.

    Args:
      url: The Identity-Aware Proxy-protected URL to fetch.
      client_id: The client ID used by Identity-Aware Proxy.
      method: The request method to use
              ('GET', 'OPTIONS', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE')
      **kwargs: Any of the parameters defined for the request function:
                https://github.com/requests/requests/blob/master/requests/api.py
                If no timeout is provided, it is set to 90 by default.

    Returns:
      The page body, or raises an exception if the page couldn't be retrieved.
    """
    # Set the default timeout, if missing
    if "timeout" not in kwargs:
        kwargs["timeout"] = 90

    # Obtain an OpenID Connect (OIDC) token from metadata server or using service
    # account.
    open_id_connect_token = id_token.fetch_id_token(Request(), client_id)

    # Fetch the Identity-Aware Proxy-protected URL, including an
    # Authorization header containing "Bearer " followed by a
    # Google-issued OpenID Connect token for the service account.
    resp = requests.request(
        method,
        url,
        headers={"Authorization": "Bearer {}".format(open_id_connect_token)},
        **kwargs
    )
    if resp.status_code == 403:
        raise Exception(
            "Service account does not have permission to "
            "access the IAP-protected application."
        )
    elif resp.status_code != 200:
        raise Exception(
            "Bad response from application: {!r} / {!r} / {!r}".format(
                resp.status_code, resp.headers, resp.text
            )
        )
    else:
        return resp.text

Ruby

To authenticate to IAP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

# url = "The Identity-Aware Proxy-protected URL to fetch"
# client_id = "The client ID used by Identity-Aware Proxy"
require "googleauth"
require "faraday"

# The client ID as the target audience for IAP
id_token_creds = Google::Auth::Credentials.default target_audience: client_id

headers = {}
id_token_creds.client.apply! headers

resp = Faraday.get url, nil, headers

if resp.status == 200
  puts "X-Goog-Iap-Jwt-Assertion:"
  puts resp.body
else
  puts "Error requesting IAP"
  puts resp.status
  puts resp.headers
end

Obtaining an OIDC token from a local service account key file

If you have a service account key file, you can adapt the preceding code samples to provide the service account key file.

Bash

  #!/usr/bin/env bash
  set -euo pipefail

  get_token() {
    # Get the bearer token in exchange for the service account credentials.
    local service_account_key_file_path="${1}"
    local iap_client_id="${2}"

    local iam_scope="https://www.googleapis.com/auth/iam"
    local oauth_token_uri="https://www.googleapis.com/oauth2/v4/token"

    local private_key_id="$(cat "${service_account_key_file_path}" | jq -r '.private_key_id')"
    local client_email="$(cat "${service_account_key_file_path}" | jq -r '.client_email')"
    local private_key="$(cat "${service_account_key_file_path}" | jq -r '.private_key')"
    local issued_at="$(date +%s)"
    local expires_at="$((issued_at + 3600))"
    local header="{'alg':'RS256','typ':'JWT','kid':'${private_key_id}'}"
    local header_base64="$(echo "${header}" | base64)"
    local payload="{'iss':'${client_email}','aud':'${oauth_token_uri}','exp':${expires_at},'iat':${issued_at},'sub':'${client_email}','target_audience':'${iap_client_id}'}"
    local payload_base64="$(echo "${payload}" | base64)"
    local signature_base64="$(printf %s "${header_base64}.${payload_base64}" | openssl dgst -binary -sha256 -sign <(printf '%s\n' "${private_key}")  | base64)"
    local assertion="${header_base64}.${payload_base64}.${signature_base64}"
    local token_payload="$(curl -s \
      --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
      --data-urlencode "assertion=${assertion}" \
      https://www.googleapis.com/oauth2/v4/token)"
    local bearer_id_token="$(echo "${token_payload}" | jq -r '.id_token')"
    echo "${bearer_id_token}"
  }

  main(){
    # TODO: Replace the following variables:
    SERVICE_ACCOUNT_KEY="service_account_key_file_path"
    IAP_CLIENT_ID="iap_client_id"
    URL="application_url"

    # Obtain the ID token.
    ID_TOKEN=$(get_token "${SERVICE_ACCOUNT_KEY}" "${IAP_CLIENT_ID}")
    # Access the application with the ID token.
    curl --header "Authorization: Bearer ${ID_TOKEN}" "${URL}"
  }

  main "$@"

Obtaining an OIDC token in all other cases

In all other cases, use the IAM credentials API to generate an OIDC token by impersonating a target service account right before accessing a IAP-secured resource. This process involves the following steps:

1. Provide the calling service account (the service account associated with the code that is obtaining the ID token) with the Service Account OpenID Connect Identity Token Creator role (roles/iam.serviceAccountOpenIdTokenCreator).

   This gives the calling service account the ability to impersonate the target service account.

2. Use the credentials provided by the calling service account to call the generateIdToken method on the target service account.

   Set the audience field to your client ID.

For step-by-step instructions, see Create an ID token.

Authenticating from Proxy-Authorization Header

If your application uses the Authorization request header, you can include the ID token in a Proxy-Authorization: Bearer header instead. If a valid ID token is found in a Proxy-Authorization header, IAP authorizes the request with it. After authorizing the request, IAP passes the Authorization header to your application without processing the content.

If no valid ID token is found in the Proxy-Authorization header, IAP continues to process the Authorization header and strips the Proxy-Authorization header before passing the request to your application.

What's next

• Learn more about Authorization: Bearer Tokens.
• Try Sign-In for Android or Sign-In for iOS.