Google Identity#

Introduction#

The google-identity method uses OpenID Connect to authenticate Google Workspace users as SFTPPlus administrators or file transfer accounts. Register SFTPPlus in Google Cloud and configure the generated client credentials in SFTPPlus, as described below. Configure workspace_names with the Workspace domains whose users may sign in.

Warning

Register SFTPPlus as an Internal application in Google Auth Platform. Set Audience > User type to Internal to restrict sign-in to your Google Workspace organization.

Google Identity does not provide group membership to SFTPPlus. Define access permissions using SFTPPlus groups for file transfer accounts and roles for administrators.

It is recommended to configure the Google Identity authentication method as the first method in your authentication chain, before the SFTPPlus Application Accounts authentication.

SFTPPlus always asks to confirm the selected Google user for authentication. Get in touch if you would like SFTPPlus to automatically use the default Google user without a prompt.

The Google Identity authentication process should finalize in less than two minutes. For security reasons, SFTPPlus rejects delayed authentication requests.

Each authentication method allows up to 32 pending sign-ins per source IP address and 1024 in total. Users sharing a public IP address share the per-IP limit. If a limit is reached, finish a pending sign-in or wait up to two minutes before trying again.

Restarting the authentication method clears all pending sign-ins and restores the available capacity. Users with pending sign-ins must start the sign-in process again. Existing authenticated sessions are unaffected.

When using a reverse proxy, configure client_forwarded_header on the HTTP service or Web Manager to identify the original client IP address. Otherwise, all users behind that proxy share its IP address and pending sign-in limit. The proxy must replace client-supplied forwarding headers with trusted values, and clients must not be able to bypass the proxy.

For SFTPPlus to integrate with the Google Identity authentication, it needs to be able to initiate outgoing connections to the Google Cloud over HTTPS port 443. Make sure your firewall allows outgoing connections. An HTTP proxy can be used by SFTPPlus to connect to Google Cloud.

Below is the list of sub-domains used by SFTPPlus to communicate with Google Cloud:

  • accounts.google.com

  • oauth2.googleapis.com

  • openidconnect.googleapis.com

  • www.googleapis.com

Note

When using the Google authentication with SFTPPlus running behind a reverse proxy or an API gateway, make sure one of the following headers is set by your proxying setup: X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-For, or the Forwarded headers. When using the X-Forwarded-Host header, make sure it contains the port number in its value.

Note

Only authenticating administrators and HTTPS file transfer users are supported. Get in touch if you need to authenticate SFTP or FTPS users.

Configuring SFTPPlus access#

Important

Only Google Workspace accounts on custom domains are supported. They must have a verified email address and a hosted-domain (hd) claim in the Google ID token. This applies to delegated accounts, administrators, and accounts using shared base groups.

All non-Workspace accounts are rejected, including personal Gmail addresses (gmail.com and googlemail.com) and Google accounts registered with another provider's email address. For addresses managed by another provider, Google may have verified ownership before it changed.

To define file transfer access separately for each user, configure Delegated account configuration and set group_association = only-delegated-accounts.

Web Manager access always requires a delegated administrator configuration. Administrator roles are independent of base_groups, so file transfer accounts can use shared groups while administrators have individual configurations.

Set the delegated account or administrator's external_account_association to the user's Google user ID. See Finding a Google user ID for instructions on finding it. With Google users mapping set to Names or IDs (account_mapping = name-or-id), an association can also match the verified Google email address exactly. Only delegated file-transfer accounts can additionally match by their local Name when it equals that verified email address. Delegated administrators require a matching entry in External account association; their local Name is not used for matching. Authentication fails if no enabled, permitted configuration matches. SFTPPlus checks its source_ip_filter and the access restrictions of its associated groups or roles before granting access.

Warning

Selecting group_association = base-groups-or-delegated-accounts grants file transfer access to users accepted by the Google application even without a matching delegated account, subject to workspace_names, the email ownership checks above, and the groups' access restrictions. A matching delegated account supplies its own groups and access restrictions; other users receive the base groups. Restrict who can access the SFTPPlus application in your Google configuration before enabling shared base groups.

Google Identity supports only-delegated-accounts and base-groups-or-delegated-accounts for group_association; other values prevent the method from starting. The roles_association and base_roles options are ignored by Google Identity.

Finding a Google user ID#

Use the Google user's unique ID in external_account_association, one ID per line. This is the ID token's sub value, also exposed as id by the Google Directory API. See Google's user ID token documentation. The same lookup applies to delegated accounts and administrators.

A Google Workspace administrator can look up an ID by email address:

  1. Open Google's Directory API users.get reference and its API Explorer.

  2. Set userKey to the user's full primary email address or email alias.

  3. Authorize the request with a Workspace administrator permitted to read users, using the https://www.googleapis.com/auth/admin.directory.user.readonly scope.

  4. Execute the request and copy the response's id string. Check primaryEmail to confirm that the response identifies the intended user.

  5. Paste the ID into External account association for the SFTPPlus delegated account or administrator. Keep Google users mapping set to Only IDs.

Alternatively, obtain the ID from an SFTPPlus authentication failure:

  1. With delegated-only access configured, ask the intended user to sign in through Google before adding their external association.

  2. In Web Manager's Activity Log, find the failed authentication for that attempt. A missing-association error includes both the remote ID and the verified Google email address.

  3. Confirm the username belongs to the intended user, then copy the remote ID into External account association and retry sign-in.

Only a missing-association failure provides this information. Failures before Google identity verification, such as rejected tokens, do not provide an authenticated user ID.

Google Identity app configuration#

Configure the following settings for your organization:

  • Create a dedicated project for SFTPPlus in Google Cloud, or select an existing project.

  • Set up Google Auth Platform for the SFTPPlus project.

  • Create credentials for SFTPPlus.

  • Set up the authentication consent page and access scopes.

  • In Google Workspace Admin, grant access to Google users for the SFTPPlus project.

Google Cloud project setup#

We recommend creating a separate project for each SFTPPlus installation.

Google Auth Platform setup#

Once you have created a new project or selected an existing project, start by setting up the Google Auth Platform for your project.

Branding

In the Branding page, add information to be visible to SFTPPlus users during the Google authentication process.

Audience

In the Audience page, explicitly select Internal as the User type. This restricts sign-in to users within your Google Workspace organization.

Clients

In the Clients page, create a new OAuth 2.0 Client for SFTPPlus.

The credentials are used to identify and authorize access to Google Cloud for a specific SFTPPlus installation or deployment.

Select Web Application as the application type, then define a name for these credentials. Our suggestion is to use a name like SFTPPlus UK PROD-01 or something that indicates which SFTPPlus installation uses these credentials.

Authorized JavaScript origins are not required for SFTPPlus and can be left empty.

Authorized redirect URIs configuration is required for SFTPPlus operation.

Define the URL using the following format, where SERVER:PORT is replaced with the address for your HTTPS web file browser, and AUTH-UUID with the unique ID of this authentication method: https://SERVER.COM:PORT/?redirect-AUTH-UUID

Data access

Use the Add or remove scope button to configure the scopes required by SFTPPlus.

The following API scopes are required:

  • openid - for generic authentication

  • https://www.googleapis.com/auth/userinfo.email - for finding the email and using it as username

Google Workspace Access#

Inside the Google Admin console, go to Security > Access and data control > API controls.

Select Manage 3rd party apps, then proceed with adding the SFTPPlus application.

Click Configure new app. Use the client ID of the credentials that were previously created for SFTPPlus and click Search.

Once the SFTPPlus credentials are located, you can enable access for SFTPPlus to all users from your organization or to selected organization units.

From the Access to Google Data configuration page, select Specific Google data, then continue to confirm the new configuration.

Note

At this point, Google Cloud only allows settings access to 3rd party web apps based on the Organizational Unit.

name#

Default value:

''

Optional:

Yes

From version:

2.10.0

Values:

  • Any text.

Description:

Human-readable short text used to identify this method.

description#

Default value:

''

Optional:

Yes

From version:

2.10.0

Values:

  • Any text.

Description:

Human-readable text that describes the purpose of this authentication method.

type#

Default value:

''

Optional:

No

From version:

2.10.0

Values:

  • application - Application accounts.

  • os - Accounts authenticated by the OS.

  • http - HTTP (unsecured).

  • ldap - Authenticate against an LDAP server.

  • local-file - Authenticate the accounts from a separate local file.

  • radius - Authenticate via a RADIUS server.

  • entra-id - Microsoft Entra ID

  • google-identity - Google Identity

Description:

This option specifies the type of the method. Each type has a set of specific configuration options

client_id#

Default value:

Empty

Optional:

No

Values:

  • Text

From version:

5.11.0

Description:

Client ID of the SFTPPlus credentials inside Google Cloud API. This value is obtained after creating new credentials for SFTPPlus.

password#

Default value:

Empty

Optional:

Yes

Values:

  • plain text

From version:

5.11.0 This is the client secret generated by Google Cloud API for the SFTPPlus application.

tls_trusted_certificates#

Default value:

Empty

Optional:

Yes

Values:

  • Empty

  • UUID of a trusted-certificates vault item.

From version:

5.26.0

Description:

Defines additional certificate authorities trusted for outgoing Google Cloud HTTPS connections.

The Google certificate authorities distributed with SFTPPlus are always trusted. Leave this empty when no additional certificate authority is required.

group_association#

Default value:

only-delegated-accounts

Optional:

Yes

Values:

  • only-delegated-accounts

  • base-groups-or-delegated-accounts

From version:

6.3.0

Description:

Defines how file transfer users receive their SFTPPlus groups and access settings. With only-delegated-accounts, a matching delegated account supplies these settings and base_groups is ignored. With base-groups-or-delegated-accounts, SFTPPlus first looks for a matching delegated account using external_account_association and account_mapping. A match supplies its own groups and access settings; base groups are not added. Only users without a matching delegated account receive base_groups. A disabled, expired, ambiguous, or otherwise invalid matching account does not fall back to base groups. See Configuring SFTPPlus access for the matching requirements and shared-group security warning.

base_groups#

Default value:

Empty

Optional:

Yes

Values:

  • Empty

  • Group UUID.

  • Comma-separated list of group UUIDs.

From version:

5.11.0

Description:

Defines the SFTPPlus groups assigned to users without a matching delegated account when group_association = base-groups-or-delegated-accounts. At least one group UUID is required in this mode. The first configured base group is also the primary group. This option is ignored when group_association = only-delegated-accounts.

proxy#

Default value:

''

Optional:

Yes

Values:

  • URI like expression.

  • connect://12.342.421.2:3128

  • disabled (since 5.14.0)

From version:

5.11.0

Description:

This configures the proxy used by SFTPPlus to connect to the cloud services.

For now, only the HTTP/1.1 CONNECT tunnelling proxy method is supported.

Leave it empty to use the general proxy configuration.

workspace_names#

Default value:

Empty

Optional:

Yes

From version:

6.3.0

Values:

  • Google Workspace domains, separated by commas.

Description:

Restricts sign-in to users from the listed Google Workspace domains. For example, enter example.com, not the organization's display name. An empty list denies all Google sign-ins.

SFTPPlus compares the domain in Google's verified hosted-domain claim (hd) against this list, ignoring case. Matching is exact: listing example.com does not allow other.example.com. The email address suffix is not used for this check. This restriction applies to delegated accounts, administrators, and accounts using base groups.

account_mapping#

Default value:

only-id

Optional:

Yes

From version:

6.3.0

Values:

  • only-id

  • name-or-id

Description:

Controls how Google identities match external_account_association on delegated accounts and administrators. This option is labeled Google users mapping in Web Manager. With Only IDs (only-id), entries must match the verified ID token's sub exactly. With Names or IDs (name-or-id), entries can also match the verified Google email address exactly, including letter case. The email address comes from the ID token's email claim, with email_verified set to true. The user's display name is not used for matching.

With Names or IDs, only delegated file-transfer accounts can additionally match by their local Name (name) when it equals the verified Google email address exactly. Delegated administrators require a matching external_account_association entry; their local Name is not used for matching.

Note

name-or-id is safe when trusted Google Workspace administrators control primary email address changes and reassignment. Ordinary Workspace users cannot change their own sign-in username or primary email address. Changing a display name does not change the email address used for matching. See Google's username and email address documentation.

We recommend only-id to prevent accidental access changes caused by user renaming or email address reassignment. The user ID remains associated with the same Google account when its email address changes. With name-or-id, administrators must review SFTPPlus associations whenever an email address is renamed or assigned to another user.

api_scopes#

Default value:

Empty

Optional:

Yes

Values:

  • Google Cloud API scope name

  • Multiple scope names, one scope per line.

From version:

5.14.0 This allows SFTPPlus to ask for extra Google Cloud API permissions when an account is authenticated.

The extra API access token is available to the SFTPPlus Python API extensions. It is used for implementing custom extensions that integrate with Google Cloud.

You can leave this empty if you don't plan to use custom SFTPPlus extensions.

Multiple API scopes can be defined. Each scope should be defined on a separate line.