Secure access to SaaS applications

console

To create a secure gateway resource, do the following:

1. In the Google Cloud console, go to the secure gateway page.
   Go to secure gateway
2. Select the project you want to create the secure gateway for.
3. To create a secure gateway, click Create new gateway and wait for the gateway creation process to complete.
4. You can track the progress in the Notifications section of the Google Cloud console.
5. Before you create a SaaS application resource, we recommend that you create SaaS egress hubs. The hubs flag represents the regional resources required for enabling egress connectivity to the target application. You can configure one hub for each region, and each hub provides two IP addresses. A Secure Gateway can have at most 20 hubs. You can specify the following regions:
   • africa-south1
   • asia-east1
   • asia-south1
   • asia-south2
   • asia-southeast1
   • europe-central2
   • europe-north1
   • europe-southwest1
   • europe-west1
   • europe-west2
   • europe-west3
   • europe-west4
   • europe-west8
   • europe-west9
   • northamerica-northeast1
   • northamerica-northeast2
   • northamerica-south1
   • southamerica-east1
   • southamerica-west1
   • us-central1
   • us-east1
   • us-east4
   • us-east5
   • us-west1
6. In the Google Cloud console, go to the SaaS Egress Hubs page.
   Go to SaaS Egress Hubs
7. Select the project you want to create the SaaS Egress Hubs for.
8. To add a SaaS egress hub, click Add SaaS egress hub.
9. From the drop-down list, select the regions where you'd like to add the egress hubs. To add the egress hubs, click Add SaaS egress hub to add more than one hub. After you're done, click Save to create the egress hubs.

gcloud

To create a secure gateway resource, run the following command. For the --hubs flag, specify one or more regions from the following list.

gcloud beyondcorp security-gateways create SECURITY_GATEWAY_ID \
    --project=PROJECT_ID \
    --location=global \
    --display-name="SECURITY_GATEWAY_DISPLAY_NAME" \
    --hubs=us-central1
      

The hubs flag sets the regional resources required for enabling egress connectivity to the target application. You can have one hub for each region, and each hub provides two IP addresses. A Secure Gateway can have at most 20 hubs. You can specify the following regions:

• africa-south1
• asia-east1
• asia-south1
• asia-south2
• asia-southeast1
• europe-central2
• europe-north1
• europe-southwest1
• europe-west1
• europe-west2
• europe-west3
• europe-west4
• europe-west8
• europe-west9
• northamerica-northeast1
• northamerica-northeast2
• northamerica-south1
• southamerica-east1
• southamerica-west1
• us-central1
• us-east1
• us-east4
• us-east5
• us-west1

REST

To create a secure gateway resource, call the Create API method with the gateway details in the request body. For the hubs flag, specify one or more regions from the following list.

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{ "display_name": "SECURITY_GATEWAY_DISPLAY_NAME", "hubs": { "us-central1": {} } }' \
    "https://beyondcorp.googleapis.com/v1/projects/PROJECT_ID/locations/global/securityGateways?security_gateway_id=SECURITY_GATEWAY_ID"
      

The hubs flag represents the regional resources required for enabling egress connectivity to the target application. You can have one hub for each region, and each hub provides two IP addresses. A Secure Gateway can have at most 20 hubs. You can specify the following regions:

• africa-south1
• asia-east1
• asia-south1
• asia-south2
• asia-southeast1
• europe-central2
• europe-north1
• europe-southwest1
• europe-west1
• europe-west2
• europe-west3
• europe-west4
• europe-west8
• europe-west9
• northamerica-northeast1
• northamerica-northeast2
• northamerica-south1
• southamerica-east1
• southamerica-west1
• us-central1
• us-east1
• us-east4
• us-east5
• us-west1

console

To configure SaaS egress hubs, do the following:

1. In the Google Cloud console, go to the SaaS Egress Hubs page.
   Go to SaaS Egress Hubs
2. On the SaaS Egress Hubs page, find the table listing the hubs. For each region you intend to use, copy all the IP addresses listed in the Static dedicated egress IPs column. Each region provides two IP addresses.
3. Add the IP addresses to the IP allowlist of your SaaS application. For example, for a GitHub application, you can follow this guide: Managing allowed IP addresses for your organization.

gcloud

To configure SaaS egress hubs, do the following:

1. Get the IP addresses allocated by the secure gateway for each hub. Two IP addresses are allocated for a region.

gcloud beyondcorp security-gateways describe SECURITY_GATEWAY_ID \
    --project=PROJECT_ID \
    --location=global
        

The following is a sample GET response of a secure gateway with hubs. In the example, hubs are created in the us-central1 and us-east1 regions, and all of the IP addresses returned in the response must be allowed in the SaaS application.

createTime: 'CREATE_TIME'
displayName: My secure gateway
hubs:
  us-central1:
    internetGateway:
      assignedIps:
      -   IP_ADDRESS_1
      -   IP_ADDRESS_2
  us-east1:
    internetGateway:
      assignedIps:
      -   IP_ADDRESS_1
      -   IP_ADDRESS_2
name: projects/PROJECT_ID/locations/global/securityGateways/SECURITY_GATEWAY_ID
state: RUNNING
updateTime: 'UPDATE_TIME'
    

2. Add the IP addresses to the IP allowlist of your SaaS application. For example, for a GitHub application, you can follow this guide: Managing allowed IP addresses for your organization.

REST

To configure SaaS egress hubs, do the following:

1. Get the IP addresses allocated by the secure gateway for each hub. Two IP addresses are allocated for a region.

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://beyondcorp.googleapis.com/v1/projects/PROJECT_ID/locations/global/securityGateways/SECURITY_GATEWAY_ID"
        

The following is a sample GET response of a secure gateway with hubs. In the example, hubs are created in the us-central1 and us-east1 regions, and all of the IP addresses returned in the response must be allowed in the SaaS application.

{
  "securityGateways": [
    {
      "name": "projects/PROJECT_ID/locations/global/securityGateways/SECURITY_GATEWAY_ID",
      "createTime": "CREATE_TIME",
      "updateTime": "UPDATE_TIME",
      "displayName": "My secure gateway",
      "state": "RUNNING",
      "hubs": {
        "us-central1": {
          "internetGateway": {
            "assignedIps": [
              "IP_ADDRESS_1",
              "IP_ADDRESS_2",
            ]
          }
        },
        "us-east1": {
          "internetGateway": {
            "assignedIps": [
              "IP_ADDRESS_1",
              "IP_ADDRESS_2",
            ]
          }
        }
      }
    }
  ]
}
    

2. Add the IP addresses to the IP allowlist of your SaaS application. For example, for a GitHub application, you can follow this guide: Managing allowed IP addresses for your organization.

console

To create a SaaS application, do the following:

1. In the Google Cloud console, go to the secure gateway page.
   Go to secure gateway
2. To create an application, click Add application.
3. Select the application type: Public application.
4. If SaaS egress hubs aren't yet configured for this secure gateway, you will be prompted to create them. Public applications require at least one SaaS egress hub. To configure SaaS egress hubs, click Go to SaaS egress hubs and add one or more regions.
5. After you have one or more egress hubs, click Next.
6. Enter the application details:
   • Application name: Enter a name, for example, GitHub.
   • Domain matchers: Enter a comma-separated list of domain patterns to route through the secure gateway. Include the port in the format domain:port. Wildcards (*) are allowed. For example: github.com:443.
7. To configure your SaaS application, click Continue.
8. Configure your SaaS application to allow traffic from the secure gateway:
1. Carefully note or copy all the IP addresses listed for the regions you are using. These IP addresses are unique to your secure gateway.
2. Sign in to your SaaS application's administration console.
3. Navigate to the network settings or security settings where IP allowlists are managed.
4. Add all the IP addresses obtained to the application's IP allowlist.
9. To add the application, click Continue.
10. To create, save your settings and create the application, click Create.

gcloud

To create a SaaS application using gcloud, run the following command:

gcloud beyondcorp security-gateways applications create APPLICATION_ID \
    --project=PROJECT_ID \
    --security-gateway=SECURITY_GATEWAY_ID \
    --location=global \
    --display-name="APPLICATION_DISPLAY_NAME" \
    --endpoint-matchers="hostname=HOST_NAME,ports=443"
      

REST

To create a SaaS application using the REST API, run the following command:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -X POST \
    -d "{ \"display_name\": \"APPLICATION_DISPLAY_NAME\", \"endpoint_matchers\": [{hostname: \"HOST_NAME\", ports: 443}] }" \
    "https://beyondcorp.googleapis.com/v1/projects/PROJECT_ID/locations/global/securityGateways/SECURITY_GATEWAY_ID/applications?application_id=APPLICATION_ID"
      

console

Create a gateway-level policy

To configure an access policy, do the following:

1. To create a policy that applies to multiple applications linked to the secure gateway, go to the Policies page.
   Go to Policies
2. To add access policies to applications, click Create Policy.
3. From the drop-down list, select the applications that you'd like the policies to apply to.
4. Add principals to the policy:

   Principals can be users, groups, domains, or service accounts. These principals are granted or denied access based on the access levels you assign.

   1. To add a principal, click Add principal.
   2. In the Principal field, enter the email address of the user, group, service account, or the domain name.
   3. In the Access Levels drop-down, select one or more predefined Context-Aware Access levels. Access is granted only if the principal meets the conditions of the selected access levels.

   To add more principals, click Add principal again and repeat the substeps.

   You can create and manage access levels in Access Context Manager.

5. To apply the policy to the application, click Create Policy.

Modify an application-level access policy

1. To modify a policy for a single application, go to the Applications page.
   Go to Applications
2. To find the application that you want to edit, do the following:
   1. In the Applications list, search for the application that you want to modify.
   2. To view the application details, click the More actions menu (more_vert) and select View Details.
3. To edit the application, click Edit.
4. Add principals to the policy:

   Principals can be users, groups, domains, or service accounts. These principals are granted or denied access based on the access levels you assign.

   1. To add a principal, click Add principal.
   2. In the Principal field, enter the email address of the user, group, service account, or the domain name.
   3. In the Access Levels drop-down list, select one or more predefined Context-Aware Access levels. Access is granted only if the principal meets the conditions of the selected access levels.

   To add more principals, click Add principal again and repeat the substeps.

   You can create and manage access levels in Access Context Manager.

5. To apply the policy to the application, click Save.

gcloud

Safely update an access policy

The setIamPolicy command replaces the entire existing policy with the one that you provide. To avoid accidentally removing existing permissions, we recommend that you use the following "read-modify-write" pattern. This pattern helps prevent accidental removal of existing permissions.

1. Read: First, get the current access policy.
2. Modify: Edit the policy file locally to add or change permissions.
3. Write: Apply your updated policy file.

Get the current policy

Retrieve the current policy before making any changes. The etag field in the policy acts as a version identifier. It prevents conflicting updates if multiple administrators make changes simultaneously.

The following command retrieves the policy and saves it to a file named policy.json.

gcloud beta beyondcorp security-gateways applications get-iam-policy APPLICATION_ID \
    --security-gateway=SECURITY_GATEWAY_ID \
    --project=PROJECT_ID \
    --location=global > policy.json
      

Replace the following:

• APPLICATION_ID: the ID of the application resource
• SECURITY_GATEWAY_ID: the ID of the secure gateway
• PROJECT_ID: the ID of the project where the secure gateway is configured

The command creates a policy.json file that contains the current policy.

Modify the policy file

Open the policy.json file in a text editor. To grant a group access to use the secure gateway, add the group to the members list for the roles/beyondcorp.securityGatewayUser role.

The policy.json file is similar to the following example:

{
  "version": 3,
  "bindings": [
    {
      "role": "roles/beyondcorp.securityGatewayUser",
      "members": [
        "group:existing-group@example.com"
      ]
    }
  ],
  "etag": "BwXN8_d-bOM="
}
    

To add an additional group, add a new entry to the members array. Include a comma after the preceding entry. The following example adds new-group@example.com:

{
  "version": 3,
  "bindings": [
    {
      "role": "roles/beyondcorp.securityGatewayUser",
      "members": [
        "group:existing-group@example.com",
        "group:new-group@example.com"
      ]
    }
  ],
  "etag": "BwXN8_d-bOM="
}
    

You can also add other types of members, such as serviceAccount, user, group, principal, and principalSet, in policy bindings. See IAM principals for more information.

Apply the updated policy

After editing and saving your policy.json file, apply it to the resource using the setIamPolicy command. This command uses the etag from your file to ensure that you update the correct version.

gcloud beta beyondcorp security-gateways applications set-iam-policy APPLICATION_ID policy.json \
    --security-gateway=SECURITY_GATEWAY_ID \
    --project=PROJECT_ID \
    --location=global
    

Replace the following:

• APPLICATION_ID: the ID of the application resource
• SECURITY_GATEWAY_ID: the ID of the secure gateway
• PROJECT_ID: the ID of the project where the secure gateway is configured

Add a conditional access policy

You can also set access policies with conditions. Conditions specify requirements, such as a user's IP address originating from a specific location.

The following example policy grants access only if the source IP address is within a specified access level:

  {
    "version": 3,
    "bindings": [
      {
        "role": "roles/beyondcorp.securityGatewayUser",
        "members": [
          "group:group@example.com"
        ],
        "condition": {
          "expression": "request.auth.access_levels.contains('accessPolicies/1234567890/accessLevels/in_us')",
          "title": "Source IP must be in US"
        }
      }
    ],
    "etag": "BwXN8_d-bOM="
  }

To apply this policy, follow the steps described earlier.

REST

Safely update an access policy

The setIamPolicy command replaces the entire existing policy with the one that you provide. To avoid accidentally removing existing permissions, we recommend that you use the following "read-modify-write" pattern. This pattern helps prevent accidental removal of existing permissions.

1. Read: Save the current access policy to a file.
2. Modify: Edit the policy file locally to add or change permissions.
3. Write: Apply your updated policy file.

Get the current policy

Retrieve the current policy before making any changes. The etag field in the policy acts as a version identifier. It prevents conflicting updates if multiple administrators make changes simultaneously.

The following command retrieves the policy and saves it to a file named policy.json.

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://beyondcorp.googleapis.com/v1/projects/PROJECT_ID/locations/global/securityGateways/SECURITY_GATEWAY_ID/applications/APPLICATION_ID:getIamPolicy" > policy.json
  

Replace the following:

• PROJECT_ID: the ID of the project where the secure gateway is configured
• SECURITY_GATEWAY_ID: the ID of the secure gateway
• APPLICATION_ID: the ID of the application resource

The command creates a policy.json file that contains the current policy.

Modify the policy file

To grant a group access to use the secure gateway, do the following:

1. Open the policy.json file in a text editor.
2. Add the group to the members list for the roles/beyondcorp.securityGatewayUser role.

The policy.json file is similar to the following example:

{
  "version": 3,
  "bindings": [
    {
      "role": "roles/beyondcorp.securityGatewayUser",
      "members": [
        "group:existing-group@example.com"
      ]
    }
  ],
  "etag": "BwXN8_d-bOM="
}
      

To add an additional group, add a new entry to the members array. Include a comma after the preceding entry. The following example adds new-group@example.com:

{
  "version": 3,
  "bindings": [
    {
      "role": "roles/beyondcorp.securityGatewayUser",
      "members": [
        "group:existing-group@example.com",
        "group:new-group@example.com"
      ]
    }
  ],
  "etag": "BwXN8_d-bOM="
}
    

You can also add other types of members, such as serviceAccount, user, group, principal, and principalSet, in policy bindings. See IAM principals for more information.

Apply the updated policy

After editing and saving your policy.json file, apply it to the resource using the setIamPolicy command. This command uses the etag from your file to ensure that you update the correct version.

jq '{policy: .}' policy.json | curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d @- \
    "https://beyondcorp.googleapis.com/v1/projects/PROJECT_ID/locations/global/securityGateways/SECURITY_GATEWAY_ID/applications/APPLICATION_ID:setIamPolicy"
  

Replace the following:

• PROJECT_ID: the ID of the project where the secure gateway is configured
• SECURITY_GATEWAY_ID: the ID of the secure gateway
• APPLICATION_ID: the ID of the application resource

Add a conditional access policy

You can also set access policies with conditions. Conditions specify requirements, such as a user's IP address originating from a specific location.

The following example policy grants access only if the source IP address is within a specified access level:

{
  "version": 3,
  "bindings": [
    {
      "role": "roles/beyondcorp.securityGatewayUser",
      "members": [
        "group:group@example.com"
      ],
      "condition": {
        "expression": "request.auth.access_levels.contains('accessPolicies/1234567890/accessLevels/in_us')",
        "title": "Source IP must be in US"
      }
    }
  ],
  "etag": "BwXN8_d-bOM="
}
  

To apply this policy, follow the steps described earlier.