This guide explains how to secure an HTTP-based, on-premises app outside of Google Cloud with Identity-Aware Proxy (IAP) by deploying an IAP connector.
For more information on how IAP secures on-premises apps and resources, see the IAP for on-premises apps overview.
Before you begin
Before you begin, you need the following:
- Have the Google Cloud SDK installed.
- An HTTP-based, on-premises app that's accessible through a DNS hostname and accepts HTTPS traffic. The app must also have its own IAP instance.
- If your app isn't publicly accessible, establish a connection between
Google Cloud and your on-premises app using Cloud Interconnect.
- Learn how to set up Cloud Interconnect.
- A Cloud Identity member granted the Owner role on your Google Cloud project.
- A Google Cloud project with billing enabled.
- The DNS hostname to use as the ingress point for traffic to
Google Cloud. For example,
- The DNS hostname of your on-premises app. For example,
- An SSL or TLS certificate for the DNS hostname that is used as the ingress point for traffic to Google Cloud. An existing self-managed or Google-managed certificate can be used. If you don't have a certificate, create one using Let's Encrypt.
Enabling required APIs
To configure an IAP connector, you must enable the following APIs:
Enable the Compute Engine API.
Enable the Google Kubernetes Engine API.
Enable the Cloud Deployment Manager API V2.
Creating an IAP connector deployment
An IAP connector is a Deployment Manager template. When deployed, the template generates resources and routing rules needed to forward IAP-authenticated and -authorized requests to your on-premises app. The following sections walk through configuring and deploying an IAP connector.
To deploy an IAP connector, your Google Cloud project's Google APIs Service Agent account needs the Kubernetes Engine Admin role. This service account allows Deployment Manager to create a Google Kubernetes Engine (GKE) cluster and all the resources running in it.
To grant the Kubernetes Engine Admin role on the Google APIs Service Agent account, do the following:
- Go to the Cloud IAM page.
Go to the Cloud IAM page
- Edit the permissions of the
PROJECT_NUMBER@cloudservices.gserviceaccount.commember by clicking Edit member edit.
- Click Add another role and select Kubernetes > Kubernetes Engine Admin from the Role drop-down.
- Click Save.
Your Google APIs Service Agent account now has the Editor and Kubernetes Engine Admin roles on your project.
Creating an SSL certificate resource
A new SSL certificate resource is needed when configuring your IAP connector's HTTP(S) load balancer proxy.
To create an SSL certificate resource from the gcloud command-line tool using your SSL or TLS certificate and private key, do the following:
Create an SSL certificate resource using
compute ssl-certificates create.
gcloud compute ssl-certificates create CERTIFICATE_NAME --private-key=PRIVATE_KEY_FILE.pem --certificate=CERTIFICATE_FILE.pem
Optionally, confirm your new SSL certificate resource is available.
Downloading and configuring an IAP connector
To fit your deployment needs, your IAP connector's configurable Deployment Manager template needs to be updated. To download and configure your template:
Download the IAP connector Deployment Manager template by cloning the IAP connector GitHub repository.
Open the cloned repository's folder and update the required fields in the
iap-connector.yamlfile. For info about routing rules, see the IAP for on-premises apps overview.
resources: - name: iap-connector type: iap-connector.py properties: zone: ZONE serviceAccountName: PROJECT_NUMBER@cloudservices.gserviceaccount.com routing: - name: BACKEND_SERVICE_NAME mapping: - name: host source: SOURCE destination: DESTINATION_URL tls: - CERTIFICATE_NAMERequired fields:
- zone: The zone where the IAP connector is
deployed. For example,
- serviceAccountName: The name of the Google APIs Service Agent account that is granted the Kubernetes Engine Admin role.
- routing.mapping.source : The URL of requests coming to Google Cloud. This URL is where traffic enters the environment.
- routing.mapping.destination: The URL for the on-premises app to which IAP routes traffic after a user has been authorized and authenticated. IAP routes traffic to this URL using TLS and the application hosted there is required to provide an HTTPS endpoint.
- tls: The name of your SSL certificate resource.
- routing.name: The name of the new backend service behind the HTTP(S) load balancer.
- initialNodeCount: Initial number of nodes desired in the cluster.
By default, the initial node count is
- imageVersion: The Ambassador
image version to run. By default, the image version is
- replicas: The initial number of replicas for Ambassador deployment. By
default, the number of replicas is
To see the IAP connector specification, view the iap-connector.py.schema file.
- zone: The zone where the IAP connector is deployed. For example,
Save your updated
Deploying an IAP connector
Deploy the IAP connector and its Google Kubernetes Engine cluster by running the following gcloud command:
gcloud deployment-manager deployments create NAME_OF_DEPLOYMENT --config=iap-connector.yaml
Optionally, monitor the deployment from the Google Cloud console:
The deployment creates a Cloud Load Balancing HTTP(S) load balancer. Associate your source domain with the public IPv4 address of the load balancer by updating the DNS resource records within your domain manager.
To obtain the public IPv4 address:
Web request traffic to your app is now being forwarded from the IAP connector to your on-premises app.
Configuring the OAuth consent screen
If you haven't configured your project's OAuth consent screen, you need to do so. An email address and product name are required for the OAuth consent screen.
Go to the OAuth consent screen.
Configure consent screen
- Under Support email, select the email address you want to display as a public contact. This email address must be your email address, or a Google Group you own.
- Enter the Application name you want to display.
- Add any optional details you'd like.
- Click Save.
To change information on the OAuth consent screen later, such as the product name or email address, repeat the preceding steps to configure the consent screen.
Setting up IAP access
Go to the
Identity-Aware Proxy page.
Go to the Identity-Aware Proxy page
- Select the project you want to secure with IAP.
- Select the checkbox next to the resource you want to add members to.
- On the right side panel, click Add member.
In the Add members dialog that appears, enter the email addresses of groups or
individuals who should have the IAP-secured Web App User role for the project.
The following kinds of accounts can be members:
- Google Account: firstname.lastname@example.org
- Google Group: email@example.com
- Service account: firstname.lastname@example.org
- G Suite domain: example.com
Make sure to add a Google Account that you have access to.
- Select Cloud IAP > IAP-secured Web App User from the Roles drop-down list.
- Click Save.
Turning on IAP
- On the Identity-Aware Proxy page, under HTTPS Resources, find the name of your IAP connector deployment. To turn on IAP,
- In the Turn on IAP window that appears, click Turn On to confirm that you want IAP to secure your on-premises app. After you turn on IAP, it requires login credentials for all connections to your load balancer. Only accounts with the IAP-secured Web App User role on the project will be given access.
- Confirm IAP is enabled by navigating to the internal URL of your on-premises app. IAP is enabled if an authentication prompt appears.
IAP is now authenticating and authorizing all traffic to your on-premises app.
Securing outbound traffic
An IAP connector forwards requests to your on-premises backend once deployed. Since the Cloud IAM access policy is enforced at the IAP connector, ensure that IAP has authenticated and authorized all requests to your backend.
To confirm that outbound traffic has come through the IAP connector, check requests for a IAP-signed header. Requests authenticated and authorized by IAP have an attached IAP signed JWT header.
Updating an IAP connector deployment
The routing rules of your IAP connector can be updated and pushed to your deployed GKE cluster using the following process. For more information, see Updating a deployment.
- Update your
iap-connector.yamlfile with new routing parameters.
Run the following gcloud command:
gcloud deployment-manager deployments update NAME_OF_DEPLOYMENT
Deleting an IAP connector deployment
Deleting your IAP connector deployment turns off IAP, leaving your app without an access authentication system. All resources created by the deployment are removed, including routing rules.
To delete your IAP connector deployment:
- Go to the Deployment Manager page.
Go to the Deployment Manager page
- In the list of deployments, select the checkbox next to your IAP deployment.
- On the top of the page, click Delete.
If you need to re-create your IAP connector deployment that you deleted, you can use your original configuration file. A re-created deployment is considered a new deployment, with new resources.