|
| 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 |
0 commit comments