1 // Copyright 2024 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // Package externalaccount provides support for creating workload identity 16 // federation and workforce identity federation token providers that can be used 17 // to access Google Cloud resources from external identity providers. 18 // 19 // # Workload Identity Federation 20 // 21 // Using workload identity federation, your application can access Google Cloud 22 // resources from Amazon Web Services (AWS), Microsoft Azure or any identity 23 // provider that supports OpenID Connect (OIDC) or SAML 2.0. 24 // Traditionally, applications running outside Google Cloud have used service 25 // account keys to access Google Cloud resources. Using identity federation, 26 // you can allow your workload to impersonate a service account. 27 // This lets you access Google Cloud resources directly, eliminating the 28 // maintenance and security burden associated with service account keys. 29 // 30 // Follow the detailed instructions on how to configure Workload Identity 31 // Federation in various platforms: 32 // 33 // - Amazon Web Services (AWS): https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#aws 34 // - Microsoft Azure: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#azure 35 // - OIDC identity provider: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#oidc 36 // - SAML 2.0 identity provider: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#saml 37 // 38 // For OIDC and SAML providers, the library can retrieve tokens in fours ways: 39 // from a local file location (file-sourced credentials), from a server 40 // (URL-sourced credentials), from a local executable (executable-sourced 41 // credentials), or from a user defined function that returns an OIDC or SAML token. 42 // For file-sourced credentials, a background process needs to be continuously 43 // refreshing the file location with a new OIDC/SAML token prior to expiration. 44 // For tokens with one hour lifetimes, the token needs to be updated in the file 45 // every hour. The token can be stored directly as plain text or in JSON format. 46 // For URL-sourced credentials, a local server needs to host a GET endpoint to 47 // return the OIDC/SAML token. The response can be in plain text or JSON. 48 // Additional required request headers can also be specified. 49 // For executable-sourced credentials, an application needs to be available to 50 // output the OIDC/SAML token and other information in a JSON format. 51 // For more information on how these work (and how to implement 52 // executable-sourced credentials), please check out: 53 // https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create_a_credential_configuration 54 // 55 // To use a custom function to supply the token, define a struct that implements 56 // the [SubjectTokenProvider] interface for OIDC/SAML providers, or one that 57 // implements [AwsSecurityCredentialsProvider] for AWS providers. This can then 58 // be used when building a [Options].The [cloud.google.com/go/auth.Credentials] 59 // created from the options using [NewCredentials] can then be used to access 60 // Google Cloud resources. For instance, you can create a new client from the 61 // [cloud.google.com/go/storage] package and pass in 62 // option.WithTokenProvider(yourTokenProvider)) 63 // 64 // # Workforce Identity Federation 65 // 66 // Workforce identity federation lets you use an external identity provider 67 // (IdP) to authenticate and authorize a workforce—a group of users, such as 68 // employees, partners, and contractors—using IAM, so that the users can access 69 // Google Cloud services. Workforce identity federation extends Google Cloud's 70 // identity capabilities to support syncless, attribute-based single sign on. 71 // 72 // With workforce identity federation, your workforce can access Google Cloud resources 73 // using an external identity provider (IdP) that supports OpenID Connect (OIDC) or 74 // SAML 2.0 such as Azure Active Directory (Azure AD), Active Directory Federation 75 // Services (AD FS), Okta, and others. 76 // 77 // Follow the detailed instructions on how to configure Workload Identity Federation 78 // in various platforms: 79 // 80 // - [Amazon Web Services (AWS)](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#aws) 81 // - [Azure AD](https://cloud.google.com/iam/docs/workforce-sign-in-azure-ad) 82 // - [Okta](https://cloud.google.com/iam/docs/workforce-sign-in-okta) 83 // - [OIDC identity provider](https://cloud.google.com/iam/docs/configuring-workforce-identity-federation#oidc) 84 // - [SAML 2.0 identity provider](https://cloud.google.com/iam/docs/configuring-workforce-identity-federation#saml) 85 // 86 // For workforce identity federation, the library can retrieve tokens in three ways: 87 // from a local file location (file-sourced credentials), from a server 88 // (URL-sourced credentials), or from a local executable (executable-sourced 89 // credentials). 90 // For file-sourced credentials, a background process needs to be continuously 91 // refreshing the file location with a new OIDC/SAML token prior to expiration. 92 // For tokens with one hour lifetimes, the token needs to be updated in the file 93 // every hour. The token can be stored directly as plain text or in JSON format. 94 // For URL-sourced credentials, a local server needs to host a GET endpoint to 95 // return the OIDC/SAML token. The response can be in plain text or JSON. 96 // Additional required request headers can also be specified. 97 // For executable-sourced credentials, an application needs to be available to 98 // output the OIDC/SAML token and other information in a JSON format. 99 // For more information on how these work (and how to implement 100 // executable-sourced credentials), please check out: 101 // https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#generate_a_configuration_file_for_non-interactive_sign-in 102 // 103 // # Security considerations 104 // 105 // Note that this library does not perform any validation on the token_url, 106 // token_info_url, or service_account_impersonation_url fields of the credential 107 // configuration. It is not recommended to use a credential configuration that 108 // you did not generate with the gcloud CLI unless you verify that the URL 109 // fields point to a googleapis.com domain. 110 package externalaccount 111