Deployment of the GCP Connector Environment

This document outlines the necessary steps to deploy the GCP Connector and correctly configure the environment. It covers the instructions for,

• Project Creation in GCP:
  A new project will be created in Google Cloud Platform (GCP) where the EID SCIM microservice will be deployed.

• Artifacts for Account Store Creation:
  After deployment, the following artifacts will be available for use in the Account Store creation wizard:

  • Service Account Email (SA2)

  • .p12 Service Account Key Certificate

  • App Engine Host Name: The base URL where the microservice is deployed.

  • JWT Target Audience (TA1)

Service Accounts & JWT Target Audiences.

This section outlines the service accounts and JWT target audiences essential for deploying the GCP Connector environment. Two service accounts, SA1 and SA2, are utilized for authentication and authorization purposes. Additionally, two JWT target audiences, TA1 and TA2, are used.

Service Accounts

Two service accounts will be used:

1. SA1: This is an App Engine default service account (or another specific account you configure). It is attached to the microservice running in the App Engine. The microservice uses this service account to authenticate with the Google API. It is an ambient account available to the microservice and is only used for deployment purposes.

2. SA2: This service account is used for OAuth2 authentication from EID to the microservice. The microservice needs to be deployed behind the Identity-Aware Proxy (IAP), which will check for authentication. This is the service account to enter in EID during the Account Creation wizard.

JWT Target Audiences

Two different JWT target audience values will be used:

1. TA1: This is the target audience to be entered in EID during Account Store creation. The value is the OAuth 2.0 Client ID of the Credentials in the APIs & Services of the GCP. It typically looks like 636363636363-p97kufa1jh000800m2k6cu01ork7xxxx.apps.googleusercontent.com .

2. TA2: This is the target audience of the verification JWT token attached by the IAP in the requests to the microservice. It is verified by the microservice and usually appears as /projects/741662800000/apps/appname and is only used for deployment purposes.

Installation Steps

1. Open the Cloud Console: https://console.cloud.google.com/

2. Create a new project

3. Enable the APIs for that project

   1. IAM Service Account Credentials API

   2. Admin SDK API

   3. Cloud Resource Manager API

   4. Identity and Access Management (IAM) API

   5. Cloud Asset API

4. Deploy the microservice to the app engine

   1. Get the gcloud CLI: Install the gcloud CLI  |  Google Cloud CLI Documentation

   2. From the command line, run: gcloud init

   3. Navigate to the package folder and run: gcloud app deploy

   4. Note: you’ll need to deploy it twice. Below, you’ll find another step requiring you to deploy it with the updated config. This time is for the app to get created and to enable the Identity-Aware Proxy, and the second time - to deploy it with the updated appsettings.json containing the correct IAP OAuth Client ID for the JWT token verification.
      
      Troubleshooting:

      1. If you see an error about the billing not being enabled, check the billing for that project and link the project to one of the billing accounts. If you cannot see any billing accounts, they may not exist, or you may not have the privilege to view them. Grant yourself the Billing Account Administrator and Organization Administrator roles. The first role will enable you to view the existing organization's billing accounts and link the new project to them.

      2. If you see an error like this: ERROR: (cloud.app.deploy) Error Response: [13] An internal error occurred, check the organization policy “Disable Automatic IAM Grants for Default Service Accounts.” It should be disabled. Disabling it will interfere with the microservice's first deployment.

5. Enable the domain-wide delegation for the App Engine service account (SA1)

   1. Get the ClientID of the App Engine service account (SA1)

      1. Go to App Engine → Settings of your project

      2. See the service account email

      3. Go to IAM & Admin → Service Accounts

      4. Find that service account and see the Client ID column

   2. Open the Admin console: https://admin.google.com/

      1. Security → Access and Data Control → API Controls → Manage Domain-wide Delegation

      2. Input the Client ID obtained at the previous step

      3. Scopes:

          

         • If you need to setup read-only access only:
           https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.orgunit.readonly, |
           https://www.googleapis.com/auth/cloud-platform.read-only,
           https://www.googleapis.com/auth/cloud-platform, https://www.googleapis.com/auth/admin.reports.audit.readonly

         • If you need to setup read & write access:
           https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.rolemanagement, https://www.googleapis.com/auth/admin.directory.orgunit,
           https://www.googleapis.com/auth/cloud-platform.read-only,
           https://www.googleapis.com/auth/cloud-platform, https://www.googleapis.com/auth/admin.reports.audit.readonly

6. At the project level, grant the Service Account Token Creator role to the App Engine service account (SA1)

   1. In the Cloud Console, Go to IAM & Admin → IAM

   2. Click Grant Access

   3. Enter the service account (SA1) email address and select the role

7. Create an IAP service account (SA2) for EID → MS connectivity and generate or upload a key for it

   1. Go to IAM & Admin → Service Accounts

   2. Create a service account

   3. Navigate to the newly created service account page

   4. Navigate to Keys

   5. Add Key → Create New Key → .p12

      1. Note: alternatively, you can upload an existing certificate public key.
         
         Troubleshooting:

         If you’re unable to upload a new key, check the organization policy “Disable Service Account Key Upload”

         If you’re unable to generate a key, check the organization policy “Disable service account key creation“

8. Enable the identity-aware proxy

   1. Go to IAM & Admin → Identity-Aware Proxy

   2. When enabling, configure the OAuth consent screen. Choosing “Only for internal users” is ok.

   3. Enable it for the microservice app (App Engine app).

   4. Grant the IAP-secured Web App User role to service account 2 (SA2) for the microservice app.

9. Get the JWT target audience for EID (TA1):

   1. Go to APIs & Services → Credentials

   2. See the OAuth 2.0 Client IDs section. Find your application and copy the Client ID value, that is your TA1, target audience to enter on the Account Store creation in EmpowerID.

10. Get the JWT target audience of the IAP JWT token for the microservice (TA2):

    1. Go to IAM & Admin → Identity-Aware Proxy

    2. Find the App Engine App in the table, scroll right, click the three dots icon, click Get JWT Audience Code

11. Configure the JWT verification values in the appsettings.json:

    1. MicroserviceConfiguration.DomainWideDelegationUser - organization admin email

    2. MicroserviceConfiguration.IapJwtExpectedAudience: set it to the value obtained at the previous step (TA2)

12. Deploy again (gcloud app deploy)

13. Grant the organization admin (the user specified in the MicroserviceConfiguration.DomainWideDelegationUser) the Cloud Asset Viewer role in the organization.

    1. Go to IAM & Admin → IAM

    2. Select the organization's’s scope

    3. Click Grant Access, populate the e-mail, and add the Cloud Asset Viewer role.

14. Get the app engine's’s public URL

    1. Go to App Engine → Services

    2. In the grid, see the “default” hyperlink in the Service column. That hyperlink address is the microservice base url. It looks like https://yourappname.uc.r.appspot.com/

    3. Navigating to that will actually not work, the IAP will ask you to authenticate and you won’t be able to (unless you’ve granted your own account the IAP-secured Web App User role too, like you did to the SA2).

Verify Deployment

While there are various methods to test if the deployment was successful, you can use the following techniques to validate its functionality:

Account Store and Inventory:

• Create an account store to manage user accounts.

• Perform an inventory to verify the correct population of data within the account store.

IAM Role Verification

• Grant yourself the "IAP-secured Web App User" role to access your App Engine or at the project level.

• Navigate to the app's public URL. Wait for the role grant to take effect (typically takes around 2 minutes). Check for a 404 error. If you see a 404 error, it indicates that the role grant has taken effect and the application is working as expected.

• Access the /QueryOrganizations endpoint. If the deployment is successful, you should see a JSON response containing information about one organization.

• Revoke the "IAP-secured Web App User" role to ensure security.