Console
Start free

Configure Workforce Identity Federation with PingFederate

This document shows you how to configure Workforce Identity Federation with the PingFederate identity provider (IdP) and manage access to Google Cloud. After you configure the PingFederate IdP, federated users can access Google Cloud services that support Workforce Identity Federation by using the SAML 2.0 protocol.

Before you begin

  • Make sure that you set up a Google Cloud organization.

  • Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    • To set up a PingFederate application that uses the SAML 2.0 protocol, do the following in PingFederate:

    1. Set the SAML 2.0 Entity ID of your PingFederate IdP. For details, see Specifying federation information.

    2. Create a SAML 2.0 SP connection, see Choosing an SP connection type and do the following:

      1. In Connection Type, select Browser SSO Profiles and SAML 2.0 protocol.
      2. In Import Metadata, select None.

    3. In General Info, set the Partner's Entity ID (Connection ID) to the following:

      https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

    4. In SAML Profiles, enable SP-initiated SSO. If you plan to also use IdP-initiated single sign-on (SSO), you can also enable it.

    5. In Attribute Contract, define custom attributes (for example, email and groups) to be passed in the assertion. These attributes can be used in Google Cloud to create access management policies later.

    6. In Attribute Contract Fulfillment, make sure that SAML_SUBJECT is mapped to a field that has a unique value for each user. For example, an email address is typically unique for each user, doesn't change, and is often used to refer to a specific user in Google Cloud access management policies.

    7. To set up console (federated) sign-in, in Assertion Consumer Service URL, add the following endpoint URL:

      https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

      Replace the following:

    8. Set Binding for this endpoint to POST.

    9. To enable console (federated) sign-in, in Allowable SAML Bindings, select Redirect.

    10. For Signature Policy, select Sign Response As Required.

    11. Save and activate the connection.

    Use attributes

    This section describes how to use attributes from the SAML assertion.

    Use attribute contracts to specify the custom attributes in the generated SAML assertions. After you configure attributes, you can use them in Google Cloud to create access management policies. To learn more about attribute contracts, refer to Attribute contracts in the PingFederate server documentation.

    For example, in this guide we use PingOne as the datastore for PingFederate and map the email, firstName, and groups attribute contracts using the user attributes from the PingOne datastore, as follows:

    Attribute Contract Value
    email email
    firstName name.given
    groups memberOfGroupIDs

    Create the PingFederate workforce identity pool provider

    This section describes how to create a workforce identity pool provider to enable your IdP users to access Google Cloud. You can configure the provider to use the SAML protocol.

    Create a SAML 2.0 workforce identity pool provider

    1. To configure the SAML application, do the following:

      gcloud

      To create the SAML workforce identity pool provider, run the following command:

      gcloud iam workforce-pools providers create-saml WORKFORCE_PROVIDER_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --idp-metadata-path="XML_METADATA_PATH" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \
    --location=global

      Replace the following:

      • WORKFORCE_PROVIDER_ID: a provider ID.
      • WORKFORCE_POOL_ID: the workforce identity pool ID.
      • DISPLAY_NAME: a display name.
      • DESCRIPTION: a description.
      • XML_METADATA_PATH: the path to the XML-formatted metadata file from PingFederate.
      • ATTRIBUTE_MAPPING: the attribute mapping; for example, google.subject=assertion.subject,google.groups=assertion.attributes.groups,attribute.department=assertion.attributes.department[0].
      • ATTRIBUTE_CONDITION: an optional attribute condition; for example, to limit the ipaddr attribute to a certain IP range, set the condition to assertion.ipaddr.startsWith('98.11.12.').

      This command assigns the subject, groups, and department in the SAML assertion to google.subject, google.groups, and attribute.department attributes, respectively. The attribute condition also ensures that only users within a certain IP range can sign in using this workforce provider.

      Console

      To configure the SAML provider by using the Google Cloud console, do the following:

      1. In the Google Cloud console, go to the Workforce Identity Pools page: Go to Workforce Identity Pools
      2. In the Workforce Identity Pools table, select the pool that you want to create the provider for.
      3. In the Providers section, click Add Provider.
      4. In the Select a Provider vendor list, select Generic Identity Provider.
      5. In Select an authentication protocol, select SAML.
      6. In the Create a provider section, do the following:
        1. In Name, enter a name for the provider.
        2. In IDP metadata file (XML), select the metadata XML file from PingFederate.
        3. Click Continue.
      7. In the Share your provider information section, click Continue.

      8. In the Configure provider section, do the following:

        1. In Attribute mapping, enter a CEL expression for google.subject (for example, assertion.subject).

        2. Optional: To enter other mappings, click Add mapping and enter other mappings—for example:

          google.subject=assertion.subject,
google.groups=assertion.attributes['https://example.com/aliases'],
attribute.costcenter=assertion.attributes.costcenter[0]

      9. To turn on detailed audit logging, in Detailed logging, click the Enable attribute value audit logging toggle.

      10. To create the provider, click Submit.

    Manage access to Google Cloud resources

    This section shows how to manage access to Google Cloud resources for PingFederate users.

    The sample project that's used in this guide can be different from the project you used to set up Workforce Identity Federation.

    You can manage roles for single identities, a group of identities, or an entire pool. For more information, see Workforce principal identifiers for allow policies.

    Use mapped department attributes

    To grant the Storage Admin role (roles/storage.admin) to all identities within a specific department for the TEST_PROJECT_ID project, run the following command:

    gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"

    Replace the following:

    Use mapped groups

    To grant the Storage Admin role (roles/storage.admin) to all identities within the GROUP_ID group for the TEST_PROJECT_ID project, run the following command:

    gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

    Replace the following:

    Sign in and test access

    In this section, you sign in as a workforce identity pool user and test your access.

    Sign in

    console (federated) sign-in

    To sign in to the Google Cloud Workforce Identity Federation console, also known as the console (federated), do the following:

  • Go to the console (federated) sign-in page.

    Go to console (federated)

  • Enter the provider name, which is formatted as follows: 
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
    • Enter your PingFederate credentials when prompted.

    gcloud CLI browser-based sign-in

    To sign in to gcloud CLI using a browser-based sign-in flow:

    Run the following command to create a login configuration file:

    Linux and macOS

    gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=LOGIN_CONFIG_PATH

    Windows (PowerShell)

    gcloud iam workforce-pools create-login-config `
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
    --output-file=LOGIN_CONFIG_PATH

    Replace the following:

    The login configuration file contains the endpoints used by the gcloud CLI to enable the browser-based authentication flow and set the audience to the IdP that was configured in the workforce identity pool provider. The file doesn't contain confidential information.

    The login configuration file content looks similar to the following:

    {
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect"
}

    Point to the login configuration file with an environment variable, a property in the active gcloud CLI configuration, or use it directly with the gcloud auth login command:

    Environment variable

    To use the login configuration file with an environment variable, complete the following instructions:

    1. Set the CLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable to the path of the login configuration file.

    2. Run the following command:

      gcloud auth login
    3. The gcloud CLI references the environment variable to find the login configuration file, and then starts the authentication process. Follow the browser-based flow to authenticate and authorize the gcloud CLI to access resources on your behalf for future commands.

    To stop using the login configuration file for gcloud auth login commands, clear the CLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable.

    gcloud CLI configuration

    To use the login configuration file with a gcloud CLI configuration property, complete the following instructions:

    1. Set the active gcloud CLI configuration's auth/login_config_file property to the login configuration file's path with the following command: 

      gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

    2. Run the following command:

      gcloud auth login
    3. The gcloud CLI references the configuration property to find the login configuration file, and then starts the authentication process. Follow the browser-based flow to authenticate and authorize the gcloud CLI to access resources on your behalf for future commands.

    To stop using the login configuration file for gcloud auth login commands, unset the property with the following command: 

    gcloud config unset auth/login_config_file

    gcloud auth login

    To use the login configuration file directly with the gcloud auth login command, complete the following instructions:

    • If you used the --activate flag when you created the login configuration file, run the following command: 

      gcloud auth login

    • If you didn't use the --activate flag when you created the login configuration file, run the following command:

      Linux and macOS

      gcloud auth login \
    --login-config=LOGIN_CONFIG_PATH

      Windows (PowerShell)

      gcloud auth login `
    --login-config=LOGIN_CONFIG_PATH

      Replace LOGIN_CONFIG_PATH with the path of your login configuration file.

    The gcloud auth login command stores access credentials in your home directory. The authenticated principal becomes the active principal in your active gcloud CLI configuration. Unless overridden, the gcloud CLI uses these stored credentials to access Google Cloud.

    gcloud CLI headless sign-in

    To sign in to PingFederate with the gcloud CLI using the SAML protocol, do the following:

    1. Sign in a user to your PingFederate app and get the SAML response.
    2. Save the SAML response returned by PingFederate in a secure location on your local machine. Store the path in an environment variable—for example: SAML_ASSERTION_PATH=/path/to/assertion.xml.

    3. Generate a configuration file:

      gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --credential-source-file=SAML_ASSERTION_PATH \
    --workforce-pool-user-project=PROJECT_ID \
    --output-file=config.json

      Replace the following:

      • SAML_ASSERTION_PATH: the path of the SAML assertion file.
      • PROJECT_ID: the project ID.

    4. The configuration file that's generated looks similar to the following:

      {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "SAML_ASSERTION_PATH"
  },
  "workforce_pool_user_project": "PROJECT_ID"
}

    5. To sign in to the gcloud CLI using token exchange, run the following command:

      gcloud auth login --cred-file=config.json

      gcloud then transparently exchanges your PingFederate credentials for temporary Google Cloud access tokens, allowing you to make other gcloud calls to Google Cloud. The output is similar to the following:

      Authenticated with external account user credentials for: [principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

    6. To list the credentialed accounts and the active account, run the following command:

      gcloud auth list

    Test access

    You have access to Google Cloud services that support Workforce Identity Federation and to which you are granted access. Earlier in this guide, you granted the Storage Admin role to all identities within a specific department or group for project TEST_PROJECT_ID. You can test that you have access by listing Cloud Storage buckets.

    console (federated) sign-in

    To verify your access in the console (federated), do the following:

    1. Go to the Cloud Storage page.
    2. Verify that you can see the list of existing buckets for the project TEST_PROJECT_ID.

    gcloud CLI

    To list Cloud Storage buckets and objects for the project that you have access to, run the following command:

    gcloud alpha storage ls --project="TEST_PROJECT_ID"

    The principal must have the serviceusage.services.use permission on the project set in the gcloud CLI session: PROJECT_ID.

    What's next