This guide shows you how to configure workforce identity federation using Azure AD as an identity provider (IdP), manage access, and sign in users to access Google Cloud services that support workforce identity federation.
Before you begin
You must have a Google Cloud organization set up.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
In Azure AD, ensure that ID Tokens are enabled for implicit flow. For more information, see Enable the implicit flow.
Your IdP must provide signed authentication information: OIDC IdPs must provide a JWT, and SAML IdP responses must be signed.
Required roles
To get the permissions that you need to configure workforce identity federation,
ask your administrator to grant you the
IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin
) IAM role on the organization.
For more information about granting roles, see
Manage access.
You might also be able to get the required permissions through custom roles or other predefined roles.
Alternatively, the IAM Owner (roles/owner
) basic role also
includes permissions to configure identity federation.
You should not grant basic roles in a production environment, but you can grant them in a
development or test environment.
Create a workforce identity pool
To create the workforce identity pool, run the following command:
gcloud iam workforce-pools create WORKFORCE_POOL_ID \
--organization=ORGANIZATION_ID \
--location=global
Replace the following:
WORKFORCE_POOL_ID
: an ID that you choose to represent your Google Cloud workforce identity pool. For information on formatting the ID, see the Query parameters section in the API documentation.ORGANIZATION_ID
: the numeric organization ID of your Google Cloud organization.
Create an Azure AD app
This section provides the steps to create an Azure AD app using the Microsoft Azure Portal. For additional details, see What is authentication.
Workforce identity pools support federation using both OIDC and SAML protocols.
OIDC
To create a Microsoft app registration that uses the OIDC protocol, perform the following steps:
- Sign in to the Microsoft Azure Portal.
- Go to Azure Active Directory > App registrations.
To begin configuring the app registration, do the following:
- Click New registration.
- Enter a name for your app.
- In Supported account types, select an option.
In the Redirect URI section, in the Select a platform drop-down list, select Web. In the text field, enter a redirect URL. Your users are redirected to this URL after they successfully sign in. If you are configuring access to the console (federated), use the following URL format:
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
Replace the following:
WORKFORCE_POOL_ID
: the ID of the workforce pool that you created earlier in this guide.WORKFORCE_PROVIDER_ID
: a workforce identity provider ID of your choice—for example:azure-ad-oidc-provider
. For information on formatting the ID, see the Query parameters section in the API documentation.
To create the app registration, click Register.
Optional: To configure a groups claim, do the following:
- Go to your Azure AD app registration.
- Click on Token configuration.
- Click on Add groups claim.
- Select the group types to return. For more details, refer to Configuring groups optional claims.
SAML
To create a Microsoft application that uses the SAML protocol, perform the following steps:
- Sign in to the Microsoft Azure Portal.
- Go to Azure Active Directory > Enterprise applications.
To begin configuring the enterprise application, do the following:
- Click on New application > Create your own application.
- Enter a name for your app.
- Click on Create.
- Go to Single sign-on > SAML.
Update the Basic SAML Configuration as follows:
In the Identifier (Entity ID) field, enter the following value:
https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID
In the Reply URL (Assertion Consumer Service URL) field, enter a redirect URL. Your users are redirected to this URL after they successfully sign in. If you are configuring access to the console (federated), use the following URL format:
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
Replace the following:
WORKFORCE_POOL_ID
: the ID of the workforce identity pool that you created earlier in this guide.WORKFORCE_PROVIDER_ID
: a workforce identity provider ID of your choice; for example:azure-ad-oidc-provider
. For information on formatting the ID, see the Query parameters section in the API documentation.
If you want to enable IdP-initiated sign-on, set the Relay State field to the following value:
https://console.cloud.google/
To save the SAML app configuration, click Save.
Optional: To configure a group claim, do the following:
- Go to your Azure AD app.
- Click on Single sign-on.
- In the Attributes & Claims section, click on Edit.
- Click on Add a group claim.
- Select the group type to return. For more details, refer to Add group claims to tokens for SAML applications using SSO configuration.
Create the Azure AD workforce identity pool provider
OIDC
To get the client ID for your Azure AD app, do the following:
- Go to your Azure AD app registration.
- Copy the Application (client) ID.
To get the issuer URL for your Azure AD app, do the following:
- Go to your Azure AD app registration.
- Click on Endpoints.
- Open the OpenID Connect metadata document in a new tab.
- Copy the value of issuer in the JSON.
To create an OIDC workforce identity pool provider that uses the implicit flow for web sign-in, run the following command:
gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
--workforce-pool="WORKFORCE_POOL_ID" \
--display-name="DISPLAY_NAME" \
--description="DESCRIPTION" \
--issuer-uri="OIDC_ISSUER_URL" \
--client-id="OIDC_CLIENT_ID" \
--web-sso-response-type="id-token" \
--web-sso-assertion-claims-behavior="only-id-token-claims" \
--attribute-mapping="ATTRIBUTE_MAPPING" \
--attribute-condition="ATTRIBUTE_CONDITION" \
--location=global
Replace the following:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce pool IDDISPLAY_NAME
: the display nameDESCRIPTION
: a descriptionOIDC_ISSUER_URL
: the issuer URL of your IdPOIDC_CLIENT_ID
: the OIDC client IDATTRIBUTE_MAPPING
: the attribute mapping—for example:google.subject=assertion.sub, google.groups=assertion.groups, google.display_name=assertion.name, attribute.department=assertion.department
ATTRIBUTE_CONDITION
: an optional attribute condition; for example, to limit theipaddr
attribute to a certain IP range you can set the conditionassertion.ipaddr.startsWith('98.11.12.')
.
This command assigns the subject
, groups
, name
, and department
attributes in
the OIDC assertion to the google.subject
, google.groups
,
google.display_name
, and attribute.department
Google Cloud attributes, respectively.
Additionally, the attribute condition ensures that only users within a
certain IP range can sign in using this workforce provider. It configures
the provider to include only ID token claims for attribute mapping and attribute condition.
SAML
To save the SAML metadata for your Azure AD app, do the following:
- Go to your Azure AD app.
- Click Single sign-on.
- In the SAML Certificates section, download the Federation Metadata XML.
- Save the metadata as a local XML file.
To create the SAML workforce identity pool provider, run the following command:
gcloud iam workforce-pools providers create-saml 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:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce identity pool IDDISPLAY_NAME
: the display nameDESCRIPTION
: a descriptionXML_METADATA_PATH
: the path to the XML-formatted metadata file with configuration metadata for the SAML identity provider.ATTRIBUTE_MAPPING
: the attribute mapping; for example:google.subject=assertion.subject, google.groups=assertion.groups, attribute.department=assertion.attributes.department[0]
ATTRIBUTE_CONDITION
: an optional attribute condition; for example, to limit theipaddr
attribute to a certain IP range you can set the conditionassertion.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. Additionally, the attribute condition ensures that
only users within a certain IP range can sign in using this workforce
provider.
Optional: Accept encrypted SAML assertions from your IdP
To enable your SAML 2.0 IdP to produce encrypted SAML assertions that can be accepted by workforce identity federation, do the following:
- In workforce identity federation, do the following:
- Create an asymmetric key pair for your workforce identity pool provider.
- Download a certificate file that contains the public key.
- Configure your SAML IdP to use the public key to encrypt SAML assertions it issues.
- In your IdP, do the following:
- Enable assertion encryption, also known as token encryption.
- Upload the public key that you created in workforce identity federation.
- Confirm that your IdP produces encrypted SAML assertions.
Create workforce identity federation SAML assertion encryption keys
This section guides you through creating an asymmetric key pair that enables workforce identity federation to accept encrypted SAML assertions.
Google Cloud uses the private key to decrypt the SAML assertions that your IdP issues. To create an asymmetric key pair for use with SAML encryption, run the following command. To learn more, see Supported SAML encryption algorithms.
gcloud iam workforce-pools providers keys create KEY_ID \ --workforce-pool WORKFORCE_POOL_ID \ --provider PROVIDER_ID \ --location global \ --use encryption \ --spec KEY_SPECIFICATION
Replace the following:
KEY_ID
: a key name of your choiceWORKFORCE_POOL_ID
: the pool IDPROVIDER_ID
: the provider ID-
KEY_SPECIFICATION
: the key specification, which can be one ofrsa-2048
,rsa-3072
, andrsa-4096
.
After the key pair is created, to download the public key into a certificate file, execute the following command. Only workload identity federation has access to the private key.
gcloud iam workforce-pools providers keys describe KEY_ID \ --workforce-pool WORKFORCE_POOL_ID \ --provider PROVIDER_ID \ --location global \ --format "value(keyData.key)" \ > CERTIFICATE_PATH
Replace the following:
KEY_ID
: the key nameWORKFORCE_POOL_ID
: the pool IDPROVIDER_ID
: the provider IDCERTIFICATE_PATH
: the path to write the certificate to—for example,saml-certificate.cer
orsaml-certificate.pem
Configure your SAML 2.0-compliant IdP to issue encrypted SAML assertions
To configure Azure AD to encrypt SAML tokens, see Configure Azure Active Directory SAML token encryption.
After you configure your IdP to encrypt SAML assertions, we recommend that you check to make sure that the assertions it generates are actually encrypted. Even with SAML assertion encryption configured, workforce identity federation can still process plaintext assertions.
Delete workforce identity federation encryption keys
To delete SAML encryption keys run the following command:gcloud iam workforce-pools providers keys delete KEY_ID \ --workforce-pool WORKFORCE_POOL_ID \ --provider PROVIDER_ID \ --location global
Replace the following:
KEY_ID
: the key nameWORKFORCE_POOL_ID
: the pool IDPROVIDER_ID
: the provider ID
Supported SAML encryption algorithms
Workforce identity federation supports the following key transport algorithms:
- http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
- http://www.w3.org/2009/xmlenc11#rsa-oaep"
- http://www.w3.org/2001/04/xmlenc#rsa-1_5"
Workforce identity federation supports the following block encryption algorithms:
Manage access to Google Cloud resources
This section provides an example that shows you how to manage access to Google Cloud resources by workforce identity federation users.
In this example, you grant an Identity and Access Management (IAM) role on a sample project. Users can then sign in and use this project to access Google Cloud products.
You can manage IAM roles for single identities, a group of identities, or an entire pool. For more information, see Represent workforce identity pool users in IAM policies.
Using mapped department attribute
To grant the Storage Admin (roles/storage.admin
) role to all identities
within a specific department for project
TEST_PROJECT_ID
, 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:
TEST_PROJECT_ID
: ID of the projectWORKFORCE_POOL_ID
: the workforce identity pool IDDEPARTMENT_VALUE
: the mappedattribute.department
value
Using mapped groups
To grant the Storage Admin (roles/storage.admin
) role to all identities
within the group GROUP_ID
for project
TEST_PROJECT_ID
, 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:
TEST_PROJECT_ID
: ID of the projectWORKFORCE_POOL_ID
: the workforce identity pool IDGROUP_ID
: a group in the mappedgoogle.groups
claim.
Sign in and test access
In this section, you sign in as a workforce identity pool user and test that you have access to a Google Cloud product.
Sign in
This section shows you how to sign in as a federated user and access Google Cloud resources.
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.
-
Enter the provider name, which is formatted as follows:
locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
- Enter user credentials in Azure AD, if prompted.
gcloud CLI browser-based sign-in
To sign in to gcloud CLI using a browser-based sign-in flow, do the following:
Create a configuration file
To create the login configuration file, run the following command. To create the interactive sign-in configuration file and activate it as the default file for the gcloud CLI, use the --activate
flag.
gcloud iam workforce-pools create-login-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \ --output-file=LOGIN_CONFIG_FILE
Replace the following:
WORKFORCE_POOL_ID
: the workforce pool IDPROVIDER_ID
: the provider IDLOGIN_CONFIG_FILE
: a path to the configuration file that you specify—for example,login.json
The file contains contains the endpoints used by the gcloud CLI to enable the browser-based authentication flow and set the audience to the provider you created earlier in this guide. The file doesn't contain confidential information.
The output looks similar to the following:
{ "type": "external_account_authorized_user_login_config", "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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", }
Sign in using browser-based authentication
To authenticate using browser-based sign-in authentication, you can use one of the following methods:
-
To sign in by specifying the location of the configuration file, run the
following command:
gcloud auth login --login-config=LOGIN_CONFIG_FILE
-
To use an environment variable to specify the location of the configuration
file, set
CLOUDSDK_AUTH_LOGIN_CONFIG_FILE
to the configuration path. -
If neither of the previous methods are specified, gcloud CLI
attempts to read the configuration from the gcloud CLI property
auth/LOGIN_CONFIG_FILE
. To set the property to the configuration path, run the following command:gcloud config set auth/login_config_file LOGIN_CONFIG_FILE
Disable browser-based sign-in
To discontinue using the login configuration file, do the following:
-
If you used the
--activate
flag when you created the configuration file, or if you activated the configuration file withgcloud config set auth/LOGIN_CONFIG_FILE
, you must run the following command to unset it:
gcloud config unset auth/login_config_file
CLOUDSDK_AUTH_LOGIN_CONFIG_FILE
environment variable, if it is set.
gcloud CLI headless sign-in
To sign in to Azure AD with the gcloud CLI, do the following:
OIDC
Follow the steps in Send the sign-in request. Sign the user into your app with Azure AD using OIDC.
Copy the ID token from the
id_token
parameter of the redirect URL and save it to a file in a secure location on your local machine. In a later step, you set PATH_TO_OIDC_ID_TOKEN to the path to this file.Generate a configuration service file similar to the one below by running the following command:
gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \ --subject-token-type=urn:ietf:params:oauth:token-type:id_token \ --credential-source-file=PATH_TO_OIDC_ID_TOKEN \ --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \ --output-file=config.json
Replace the following:
WORKFORCE_POOL_ID
: the workforce pool ID.PROVIDER_ID
: the provider ID.PATH_TO_OIDC_ID_TOKEN
: the path to the file location where the IdP token is stored.WORKFORCE_POOL_USER_PROJECT
: the project number or ID used for quota and billing. The principal must haveserviceusage.services.use
permission on this project.
When the command completes, the following config file is created by Azure AD:
{ "type": "external_account", "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID", "subject_token_type": "urn:ietf:params:oauth:token-type:id_token", "token_url": "https://sts.googleapis.com/v1/token", "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT", "credential_source": { "file": "PATH_TO_OIDC_CREDENTIALS" } }
Open the gcloud CLI and run the following command:
gcloud auth login --cred-file=PATH_TO_OIDC_CREDENTIALS
Replace PATH_TO_OIDC_CREDENTIALS with the path to the output file from a previous step.
The gcloud CLI transparently posts your credentials to the Security Token Service endpoint. In the endpoint, it is exchanged for temporary Google Cloud access tokens.
You can now run gcloud CLI commands to Google Cloud.
SAML
Sign in a user to your Azure AD app and get the SAML Response.
Save the SAML Response returned by Azure AD in a secure location on your local machine, then store the path as follows:
SAML_ASSERTION_PATH=SAML_ASSERTION_PATH
Generate a configuration file as below. Run the following command:
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:
WORKFORCE_PROVIDER_ID
: the workforce identity pool provider ID you created earlier in this guideWORKFORCE_POOL_ID
: the workforce identity pool ID you created earlier in this guideSAML_ASSERTION_PATH
: the path of the SAML assertion filePROJECT_ID
: the project ID
The configuration file that is 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" }
To login to
gcloud
using token exchange, run the following command:gcloud auth login --cred-file=config.json
gcloud
then transparently exchanges your Azure AD credentials for temporary Google Cloud access tokens, allowing you to make othergcloud
calls to Google Cloud.You see output similar to the following:
Authenticated with external account user credentials for: [principal://iam.googleapis.com/locations/global/workforcePools/
WORKFORCE_POOL_ID
/subject/USER_ID
].To list the credentialed accounts and the currently active account, run the following command:
gcloud auth list
Test Access
You now 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 for project TEST_PROJECT_ID
. You can now test
that you have access by listing Cloud Storage buckets.
console (federated)
You can now execute gcloud CLI commands to Google Cloud.
- Go to Cloud Storage page.
- Verify that you can see list of existing buckets for the
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
- Delete workforce identity federation users and their data
- Learn which Google Cloud products support workforce identity federation
- Set up user access to console (federated)