Programmatic authentication

This document describes how to authenticate to an IAP-secured resource from a user account or a service account.

Programmatic access refers to calling IAP-secured applications from non-browser clients, such as command-line tools, service-to-service calls, and mobile applications. Depending on your use case, you might want to authenticate to IAP using user credentials or service credentials.

  • 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 represents 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.

IAP supports the following types of credentials for programmatic access:

  • OAuth 2.0 ID token - A Google-issued token for a human user or service account with the audience claim set to the resource ID of the IAP application.
  • Service account signed JWT - A self-signed or Google-issued JWT token for a service account.

Include these credentials to IAP in the Authorization or Proxy-Authorization HTTP header of the request.

Before you begin

  1. Ensure you have an application that you want to access programmatically using a developer account, service account, or mobile app credentials.

  2. To create one or more OAuth 2.0 clients, see Programmatic access.

Authenticate a user account

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

Authenticate from a mobile app

  1. Create or use an existing OAuth 2.0 client ID for your mobile app. To use an existing OAuth 2.0 client ID, follow the steps in How to share OAuth Clients. Add the OAuth client ID to the allowlist for programmatic access to the application.
  2. Get an ID token for the OAuth 2.0 client ID of the IAP-secured resource.
  3. Include the ID token in an Authorization: Bearer header to make the authenticated request to the IAP-secured resource.

Authenticate from a desktop app

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

  1. To allow developers to access your application from the command line, create a desktop OAuth 2.0 client ID or share an existing desktop OAuth client ID.
  2. Add the OAuth ID to the allowlist for programmatic access for the application.

Sign in to the application

Each developer must sign in to access an IAP-secured app. You can package the process into a script, such as by using gcloud CLI. The following example uses 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.

      # Example using Netcat (http://netcat.sourceforge.net/)
  nc -k -l 4444

  3. Go to the following URI, where DESKTOP_CLIENT_ID is the Desktop app client ID:

      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:

      GET /?code=CODE&scope=email%20openid%20https://www.googleapis.com/auth/userinfo.email&hd=google.com&prompt=consent HTTP/1.1

  5. Copy the CODE value to replace CODE in the following command, along with the Desktop app client ID and secret:

      curl --verbose \
    --data client_id=DESKTOP_CLIENT_ID \
    --data client_secret=DESKTOP_CLIENT_SECRET \
    --data code=CODE