Update the service account for an SFTP user

This document shows how to update the service account for a Cloud FTP user. The service account accesses Cloud Storage resources on behalf of the user.

At a high level, these are the steps to update the service account for a user:

1. Configure a service account with the appropriate IAM roles.
2. Update the service account that's attached to the user.

We recommend that you use a dedicated service account for each user so that you can manage SFTP access separately for each user.

Required roles

To get the permission that you need to update SFTP users, ask your administrator to grant you the FTP Admin (roles/ftp.admin) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the ftp.users.update permission, which is required to update SFTP users.

You might also be able to get this permission with custom roles or other predefined roles.

Configure a service account

1. Create a service account for the user, if a service account doesn't already exist.

   gcloud iam service-accounts create USERNAME-sa \
       --description="USERNAME SFTP Service Account" \
       --display-name="USERNAME SFTP Service Account"

   Replace USERNAME with a unique username for the SFTP user. The username must start with a lowercase letter and can include lowercase letters, numbers, or hyphens.

   On success, a message like Created service account [example-userid-sa] is displayed.

2. Grant yourself the Service Account User (roles/iam.serviceAccountUser) role:

   gcloud iam service-accounts add-iam-policy-binding USERNAME-sa@PROJECT_ID.iam.gserviceaccount.com \
       --member="user:ADMINISTRATOR_EMAIL" \
       --role="roles/iam.serviceAccountUser"

   Replace ADMINISTRATOR_EMAIL with the email address of the principal who is updating the SFTP user. If you're updating the user (as opposed to an application), then this value is the email address that you use to access Google Cloud.

   On success, a message like the following is displayed:

   Updated IAM policy for serviceAccount [[e-mail]].
   bindings:
   - members:
   - user:[e-mail]
   role: roles/iam.serviceAccountUser
   etag: BwZJk7OiSzw=
   version: 1
   

3. Grant the user's service account the IAM role that's necessary to access the bucket:

   gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
       --member="serviceAccount:USERNAME-sa@PROJECT_ID.iam.gserviceaccount.com" \
       --role="ROLE"

   Replace ROLE with one of the following IAM roles:

   • For read-only access, use the roles/storage.objectViewer role.
   • For read and write access, use the roles/storage.objectAdmin role.

   Repeat this step for each bucket that the user needs to access.

4. Authorize the Cloud FTP Service Agent to generate tokens for the user's service account:

   1. Get the email address of the SFTP server's service agent. For steps, see Get details about a server.

   2. Authorize the Cloud FTP Service Agent:

      gcloud iam service-accounts add-iam-policy-binding USERNAME-sa@PROJECT_ID.iam.gserviceaccount.com \
          --member="serviceAccount:SERVICE_AGENT_EMAIL" \
          --role="roles/iam.serviceAccountTokenCreator"

      Replace SERVICE_AGENT_EMAIL with the service agent's email address.

Next, update the user's service account.

Update a user's service account

gcloud

To update the service account that's attached to an SFTP user, run the gcloud alpha storage ftp users update command.

Before using any of the command data below, make the following replacements:

• USERNAME: the SFTP user's username.
• LOCATION_ID: the location of the server, such as us-west1.
• SERVER_ID: the server ID.
• SERVICE_ACCOUNT: the user's service account. For example, [e-mail].

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud alpha storage ftp users update USERNAME --location=LOCATION_ID \
    --server=SERVER_ID --customer-service-account=SERVICE_ACCOUNT

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud alpha storage ftp users update USERNAME --location=LOCATION_ID `
    --server=SERVER_ID --customer-service-account=SERVICE_ACCOUNT

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud alpha storage ftp users update USERNAME --location=LOCATION_ID ^
    --server=SERVER_ID --customer-service-account=SERVICE_ACCOUNT

It takes a few seconds for the user to be updated.

REST

To update the service account that's attached to an SFTP user, use the servers.users.patch method. In the updateMask query parameter, provide the customerServiceAccount field.

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID of the server.
• LOCATION_ID: the location of the server, such as us-west1.
• SERVER_ID: the server ID.
• USERNAME: the SFTP user's username.
• SERVICE_ACCOUNT: the user's service account. For example, [e-mail].

HTTP method and URL:

PATCH https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID/users/USERNAME?updateMask=customerServiceAccount

Request JSON body:

{
  "customerServiceAccount": "SERVICE_ACCOUNT"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID/users/USERNAME?updateMask=customerServiceAccount"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID/users/USERNAME?updateMask=customerServiceAccount" | Select-Object -Expand Content

The response identifies a long-running operation. It takes a few seconds for the user to be updated.

What's next

• Update buckets for an SFTP user