The strict act-as mode enables an additional security check for the followinguser actions in Dataform:

• Creating or updating a repository
• Creating or updating a workflow configuration
• Creating a workflow invocation
• Updating a release configuration

This additional security check requires that the user performing these actionshas theiam.serviceAccounts.actAs permission on the effective service account,which is the service account whose credentials are used to run workflows.For more information, seeAttach service accounts to resources.

You can enable these permissions in the following ways:

• Whencreating a repository
• When updating an existing repository with thestrict_act_as_checksrepository flag

Important: We recommend enabling strict act-as mode, as this helps to ensure amore secure and predictable permissions model for your Dataformprojects.

Required roles

To get the permissions that you need to complete the tasks in this document, ask your administrator to grant you the following IAM roles:

• Service Account User (roles/iam.serviceAccountUser) on the custom service account
• View logs in Logging:Logs Viewer (roles/logging.viewer) on the project
• Grant IAM roles to users or service accounts:Service Account Admin (roles/iam.serviceAccountAdmin) on the project

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Verify act-as permissions for the effective service account

To ensure your Dataform workflows run securely and withoutinterruption, it's important to verify the act-as permissions on the serviceaccounts they use. This section explains how to identify the effective serviceaccount for your resources, use Cloud Logging to check for permission issues,and then resolve any issues you find.

Determine the effective service account

You can determine the effective service account that is running the workflowsaccording to the resource type and the following conditions:

Resource type	Effective service account
Repositories	If you select a custom service account when youcreate the repository, then theRepository.ServiceAccount service account is used. Otherwise, this defaults to theDataform service agent.
Workflow configuration	You can select a custom service account when youcreate the workflow configuration. Otherwise, this defaults to the repository'sDataform service agent.
Workflow invocation	If the compilation result isWORKFLOW_CONFIG, then the workflow configuration's effective service account is used. If you create a workflow invocation from a compilation result, then theWorkflowInvocation.InvocationConfig service account is used if it's set. Otherwise, this defaults to the repository'sDataform service agent.

Note: You can't run workflows with the defaultDataform service agent.You must use either a custom service account or your Google Accountuser credentials.

Check for permission issues in Cloud Logging

To enhance security, Dataform checks if theiam.serviceAccounts.actAs permission is missing on the service accounts usedby Dataform resources.

The results of these checks, including any potential permission issues, arerecorded in Cloud Logging. You should review these logs regularly toidentify and grant any missingiam.serviceAccounts.actAs permissions. Checkingthese logs ensures that your Dataform workflows andconfigurations continue to function without interruption.

View logs in Cloud Logging

1. In the Google Cloud console, go to theLogs Explorer page.

   Go to Logs Explorer

2. Select the Google Cloud project in which you want to check the logs.

3. Use the query editor to filter for the DataformactAslogs with the following options:

   • To list only theactAs checks that failed and require action, use thefollowing query:

     logName:"projects/PROJECT_ID/logs/dataform.googleapis.com%2Factas_dry_run_result"jsonPayload.dryRunResult=false

   • To list all of theactAs checks, use the following query:

     logName:"projects/PROJECT_ID/logs/dataform.googleapis.com%2Factas_dry_run_result"

   ReplacePROJECT_ID with yourGoogle Cloud project ID.

4. ClickRun query.

Interpret log entries

Expand a log entry in the query results to view the followingjsonPayloadfields:

Field	Type	Description
dryRunResult	Boolean	true: the permission check passed. false: the check failed. The caller principal is missing theiam.serviceAccounts.actAs permission on the service account.
caller	String	The email address of the principal (user or service account) that initiated the API call.
serviceAccount	String	The service account that the caller principal attempted to act as. This field is typically present when thedryRunResult field isfalse.
apiMethod	String	The Dataform API method that triggered the check, for example,CreateWorkflowInvocation orUpdateRepository.
*_context	Object	An object containing resource names relevant to the API method called. For more information, seeContext objects.

Important: An exception occurs whendryRunResult isfalse,serviceAccountis empty, andapiMethod isCreateWorkflowConfig,UpdateWorkflowConfg, orCreateWorkflowInvocation. This exception means that the check has failed,because no service account was specified in the API call where it's required.You must update your process to provide a service account for these operations.

Context objects

The log entry includes a context object within thejsonPayload fields. Thefields in this object contain the fully qualified Google Cloud resourcenames of the Dataform entities involved. These names follow thestandard structures shown in the following list, allowing you to preciselyidentify the resources.

• create_workflow_invocation_context: present when the API method isCreateWorkflowInvocation.

  • workflowInvocation: the resource name of the workflow invocation.
    • The format of the resource name is the following:projects/PROJECT_ID/locations/LOCATION_ID/repositories/REPOSITORY_ID/workflowInvocations/WORKFLOW_INVOCATION_ID.
  • compilationResult orworkflowConfig: the resource name of the sourceused for the invocation.
    • The format of the resource name forcompilationResult is the following:projects/PROJECT_ID/locations/LOCATION_ID/repositories/REPOSITORY_ID/compilationResults/COMPILATION_RESULT_ID.
    • The format of the resource name forworkflowConfig is the following:projects/PROJECT_ID/locations/LOCATION_ID/repositories/REPOSITORY_ID/workflowConfigs/WORKFLOW_CONFIG_ID.

• create_repository_context orupdate_repository_context: present when theAPI method isCreateRepository orUpdateRepository.

  • repository: the resource name of the Dataform repository.
    • The format of the resource name is the following:projects/PROJECT_ID/locations/LOCATION_ID/repositories/REPOSITORY_ID

• update_release_config_context: present when the API method isUpdateReleaseConfig.

  • releaseConfig: the resource name of the release configuration.
    • The format of the resource name is the following:projects/PROJECT_ID/locations/LOCATION_ID/repositories/REPOSITORY_ID/releaseConfigs/RELEASE_CONFIG_ID.

• create_workflow_config_context orupdate_workflow_config_context: presentwhen the API method isCreateWorkflowConfig orUpdateWorkflowConfig.

  • workflowConfig: the resource name of the workflow configuration.
    • The format of the resource name is the following:projects/PROJECT_ID/locations/LOCATION_ID/repositories/REPOSITORY_ID/workflowConfigs/WORKFLOW_CONFIG_ID.

To compare the documented formats to the logging entry, replace the following:

• PROJECT_ID: the unique identifier of yourGoogle Cloud project.
• LOCATION_ID: the region where yourDataform repository is located.
• REPOSITORY_ID: the user-defined ID of theDataform repository. This is the name given to the repositorywhen it was created.
• COMPILATION_RESULT_ID: the system-generated uniqueidentifier for a Dataform compilation result.
• RELEASE_CONFIG_ID: the user-defined ID of theDataform release configuration.
• WORKFLOW_CONFIG_ID: the user-defined ID of theDataform workflow configuration.

Resolve permission issues

If you find log entries where thedryRunResult field isfalse, do thefollowing:

1. In thejsonPayload details, note the email address in thecaller fieldto identify the principal.

2. Note the email address in theserviceAccount field to identify theservice account.

3. Confirm that the caller principalshould have permission to act as theservice account. Granting this permission lets the caller use the permissionsheld by the service account.

4. If the access is intended, grant theService Account User role(roles/iam.serviceAccountUser) to the caller principal on thetarget serviceaccount. For more information, seeGrant the Service Account User IAM role.

After granting the role, future logs for this combination of caller andservice account should showdryRunResult: true.

Grant the Service Account User IAM role

TheService Account User role(roles/iam.serviceAccountUser) contains theiam.serviceAccounts.actAspermission, which is required for the strict act-as mode. When you use theDataform API, you must have the Service Account User role grantedfor the effective service account based on theprojects.locations.repositories methodthat you're calling:

• createorpatch
  • If theRepository.ServiceAccount property is set, then you should havethe Service Account User role granted for that property.
  • If you're calling thepatch method, then you should havethe Service Account User role granted for all the effective serviceaccounts in all the workflow configurations in the repository.
• workflowConfigs.createorworkflowConfigs.patch
  • You should have the Service Account User role granted for the effectiveservice account used in the workflow configuration.
• releaseConfigs.patch
  • You should have the Service Account User role granted for all theeffective service accounts used in the workflow configurations using thisrelease configuration.
• workflowInvocations.create
  • You should have the Service Account User role granted for the effectiveservice account used in the workflow invocation.

To grant the Service Account User role to a custom service account, followthese steps:

1. In the Google Cloud console, go toIAM>Service accounts.

   Go to Service accounts

2. Select a project.

3. On theService accounts for project "PROJECT_NAME"page, select your custom service account.

4. Go toPrincipals with access, and then clickGrant Access.

5. In theNew principals field, enter your default Dataformservice agent ID.

   Your default Dataform service agent ID is in the followingformat:

   service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com

6. In theSelect a role list, select theService Account User role.

7. ClickSave.

For more information, see therequired roles for creating a workflow configurationand therequired roles for creating a release configuration.

Effects of strict act-as mode on automatic releases and runs

When strict act-as mode is enabled, it impacts automatic repository releasesand automatic workflow executions as follows:

For repositories thataren't connected to third-party repositories:

• You can't set aCron schedulefor automatic releases in release configurations. This is enforced to preventcode changes made by a user who might lack the necessaryiam.serviceAccounts.actAs permissions on downstream service accounts from being automatically deployed.
• Scheduled workflow runs using a Cron schedule in workflow configurations remain enabled. For these automated runs to succeed, you must grant the defaultDataform service agent theiam.serviceAccounts.actAspermission on theeffective service accountspecified in the workflow configuration.

For repositories thatare connected to third-party repositories:

• Scheduled releases and scheduled workflow runs are permitted.
• To enable an automatic release from a release configuration or an automaticrun from a workflow configuration, you must grant the default Dataform service agent theiam.serviceAccounts.actAs permissionon the relevanteffective service account:
  • For an automatic release configuration, grant the permission on theeffective service accounts of all the workflow configurations that aretriggered by this release configuration.
  • For an automatic workflow configuration, grant the permission on theeffective service account used by that workflow configuration.

Warning: Because there is no guarantee that the user writing the code has theiam.serviceAccounts.actAs permission on the effective service accounts forathird-party repository,it's your responsibility to control the code changes in third-partyrepositories with the code review process.

What's next

• To learn how to create a repository, seeCreate a repository.
• To learn more about how Dataform work with BigQuery, seeOverview of workflows.
• To learn how to create a workflow configuration, seeSchedule runs.
• To learn how to create a release configuration, seeConfigure compilations.