Programmatically creating OAuth clients for IAP

This page describes how to programmatically create OAuth clients for use with IAP, enabling you to set up IAP programmatically end-to-end for internal applications.

Known limitations

There are a few known limitations for programmatically-created OAuth clients:

• OAuth clients created by the API can only be modified by using the API. You cannot modify an OAuth client via the Cloud Console if you create it by using the API.
• Only 500 OAuth clients are allowed per project when using the API.
• API-created OAuth consent screen brands have specific limitations. See the section below for more information.

Understanding brands and branding state

The OAuth consent screen, which contains branding information for users, is known as a brand. Brands can be limited to internal users or public users. An internal brand makes the OAuth flow accessible to someone who belongs to the same G Suite organization as the project. A public brand makes the OAuth flow available to anyone on the internet.

Brands can be created manually or programmatically via an API. API-created brands are automatically configured with different settings:

• They're set to internal and must be manually set to public if desired
• They're set to an "unreviewed" state and a brand review must be triggered

To manually set an internal brand to public:

1. Open the OAuth consent screen.
2. Select your desired project from the drop-down menu.
3. On the OAuth consent screen page, note that the User Type is automatically set to Internal. To set it to Public, click Edit App. More configuration options become available.
4. Under Application type, click Public.

Note: When an API-created internal brand is set to public, the identityAwareProxyClients.create() API will stop working, as it requires the brand to be set to internal. Therefore, you cannot create new OAuth clients via the API after an internal brand is made public.

To trigger a brand review for an unreviewed API-created brand:

1. Open the OAuth consent screen.
2. Select your desired project from the drop-down menu.
3. On the OAuth consent screen page, enter any required information, and then click Submit for verification.

The verification process may take up to several weeks, and you will receive email updates as it progresses. Learn more about verification. While the verification process is ongoing, you can still use the application within your G Suite organization. Learn more about how your application will behave before it's verified.

Before you begin

Before you can create a client, first ensure that the caller has been granted the following permissions:

• clientauthconfig.brands.list
• clientauthconfig.brands.create
• clientauthconfig.brands.get
• clientauthconfig.clients.create
• clientauthconfig.clients.listWithSecrets
• clientauthconfig.clients.getWithSecret
• clientauthconfig.clients.delete
• clientauthconfig.clients.update

These permissions are included in the Editor (roles/editor) and Owner (roles/owner) primitive roles, however we recommend that you create a custom role that contains these permissions and grant it to the caller instead.

Set up OAuth for IAP

The following steps describe how to configure the consent screen and create and oauth client for IAP.

Configuring consent screen

1. Check if you already have an existing brand by using the list command. You may only have one brand per project.

   gcloud alpha iap oauth-brands list
   

   The following is an example gcloud response, if the brand exists:

   name: projects/[PROJECT_NUMBER]/brands/[BRAND_ID]
   applicationTitle: [APPLICATION_TITLE]
   supportEmail: [SUPPORT_EMAIL]
   orgInternalOnly: true
   

   Note: If a brand already exists for a project and has been configured for external users (orgInternalOnly: false), but you want to restrict it to internal users, you must make that change manually from the OAuth consent screen in order to create OAuth clients with this API.

2. If no brand exists, use the create command:

   gcloud alpha iap oauth-brands create --applicationTitle=APPLICATION_TITLE --supportEmail=SUPPORT_EMAIL
   

   The above fields are required when calling this API:

   • supportEmail: The support email displayed on the OAuth consent screen. This email address can either be a user's address or a Google Groups alias. While service accounts also have an email address, they are not actual valid email addresses, and cannot be used when creating a brand. However, a service account can be the owner of a Google Group. Either create a new Google Group or configure an existing group and set the desired service account as an owner of the group.

     Note: The user issuing the request must be an owner of the specified support email address.

   • applicationTitle: The application name displayed on OAuth consent screen.

   The response contains the following fields:

   name: projects/[PROJECT_NUMBER]/brands/[BRAND_NAME]
   applicationTitle: [APPLICATION_TITLE]
   supportEmail: [SUPPORT_EMAIL]
   orgInternalOnly: true
   

Creating an IAP OAuth Client

1. Use the create command to create a client. Use the brand name from previous step.

   gcloud alpha iap oauth-clients create projects/PROJECT-ID/brands/BRAND-ID --display_name=NAME
   

   The response contains the following fields:

   name: projects/[PROJECT_NUMBER]/brands/[BRAND_NAME]/identityAwareProxyClients/[CLIENT_ID]
   secret: [CLIENT_SECRET]
   displayName: [NAME]
   

2. Use the client ID (client_id in the above example) and secret to enable IAP. See the following topics for more information about enabling IAP using the credentials you've just created:

   • IAP for Kubernetes Engine
   • IAP for App Engine
   • IAP for Compute Engine

Authenticating

Once IAP is configured for an app, all requests need to be authenticated. The following steps describe how to access an IAP-protected application programmatically.

End user authentication

After you've followed the steps above, refer to the this topic for more information about how to authenticate using OAuth 2.0. Ensure that you request a refresh token to allow for automation. Manual consent during the OAuth flow is required, however the refresh token can be used to programmatically obtain fresh access tokens.

Service accounts and gcloud

Note: See the above section for more information about using Google Groups aliases with service accounts to ensure your support email for the OAuth consent screen is properly configured.

To authenticate using a service account and gcloud:

1. Create a service account, and grant it the required permissions.
2. Create a service account key, downloading it to the desired path.

3. Execute the following gcloud command, specifying the path to the service account key:

   gcloud auth activate-service-account [ACCOUNT-NAME]
       --key-file=/path/to/service-key.json --project=[PROJECT_ID]
   

4. Make API requests using gcloud auth print-access-token:

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)"
       https://iap.googleapis.com/v1/projects/[PROJECT_ID_OR_NUMBER]/brands