Skip to content

Commit

Permalink
feat: adds suppliers for custom subject token and AWS credentials (#1795
Browse files Browse the repository at this point in the history 
)

* feat: refactor AWS and identity pool clients to use suppliers (#1776)

* feat: refactor aws and identity pool credentials to use suppliers

* Apply suggestions from code review

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Daniel Bankhead <dan@danielbankhead.com>

* updating suppliers to use options objects

* updating docs

* moved transporter to context object and deprecated consts

* fix imports

---------

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>
Co-authored-by: Daniel Bankhead <dan@danielbankhead.com>

* feat: adds support for creating AWS and Identity Pool credentials with custom suppliers. (#1783)

* feat: adds support for users to build credentials with custom suppliers

Also adds default values to make it easier to instantiate credentials in code.

* Apply suggestions from code review

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>

* responding to review comments

---------

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>

* docs: adding documentation for programmatic auth feature (#1790)

* docs: adding documentation for programmatic auth feature

* fix typos

* Apply suggestions from code review

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>
Co-authored-by: Daniel Bankhead <dan@danielbankhead.com>

* add audience placeholder

---------

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>
Co-authored-by: Daniel Bankhead <dan@danielbankhead.com>

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* fix lint

---------

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>
Co-authored-by: Daniel Bankhead <dan@danielbankhead.com>
Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
  • Loading branch information
@aeitzman @lsirac
@danielbankhead @gcf-owl-bot
4 people committed Apr 18, 2024
1 parent b2eae07 commit c680b5d
Show file tree
Hide file tree
Showing 13 changed files with 1,744 additions and 381 deletions.
126 changes: 126 additions & 0 deletions .readme-partials.yaml
View file
Expand Up @@ -356,6 +356,55 @@ body: |-
You can now [start using the Auth library](#using-external-identities) to call Google Cloud resources from AWS.
### Accessing resources from AWS using a custom AWS security credentials supplier.
In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed:
- A workload identity pool needs to be created.
- AWS needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS).
- Permission to impersonate a service account needs to be granted to the external identity.
Follow the detailed [instructions](https://cloud.google.com/iam/docs/access-resources-aws) on how to configure workload identity federation from AWS.
If you want to use AWS security credentials that cannot be retrieved using methods supported natively by this library,
a custom AwsSecurityCredentialsSupplier implementation may be specified when creating an AWS client. The supplier must
return valid, unexpired AWS security credentials when called by the GCP credential.
Note that the client does not cache the returned AWS security credentials, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.
```ts
class AwsSupplier implements AwsSecurityCredentialsSupplier {
async getAwsRegion(context: ExternalAccountSupplierContext): Promise<string> {
// Return the current AWS region, i.e. 'us-east-2'.
}
async getAwsSecurityCredentials(
context: ExternalAccountSupplierContext
): Promise<AwsSecurityCredentials> {
const audience = context.audience;
// Return valid AWS security credentials for the requested audience.
}
}
const clientOptions = {
audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request', // Set the subject token type.
aws_security_credentials_supplier: new AwsSupplier() // Set the custom supplier.
}
const client = new AwsClient(clientOptions);
```
Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is: `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`
Where the following variables need to be substituted:
* `$PROJECT_NUMBER`: The Google Cloud project number.
* `$WORKLOAD_POOL_ID`: The workload pool ID.
* `$PROVIDER_ID`: The provider ID.
The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).
### Access resources from Microsoft Azure
In order to access Google Cloud resources from Microsoft Azure, the following requirements are needed:
Expand Down Expand Up @@ -464,6 +513,44 @@ body: |-
- `$URL_TO_GET_OIDC_TOKEN`: The URL of the local server endpoint to call to retrieve the OIDC token.
- `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`.
### Accessing resources from an OIDC or SAML2.0 identity provider using a custom supplier
If you want to use OIDC or SAML2.0 that cannot be retrieved using methods supported natively by this library,
a custom SubjectTokenSupplier implementation may be specified when creating an identity pool client. The supplier must
return a valid, unexpired subject token when called by the GCP credential.
Note that the client does not cache the returned subject token, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.
```ts
class CustomSupplier implements SubjectTokenSupplier {
async getSubjectToken(
context: ExternalAccountSupplierContext
): Promise<string> {
const audience = context.audience;
const subjectTokenType = context.subjectTokenType;
// Return a valid subject token for the requested audience and subject token type.
}
}
const clientOptions = {
audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type.
subject_token_supplier: new CustomSupplier() // Set the custom supplier.
}
const client = new CustomSupplier(clientOptions);
```
Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is: `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`
Where the following variables need to be substituted:
* `$PROJECT_NUMBER`: The Google Cloud project number.
* `$WORKLOAD_POOL_ID`: The workload pool ID.
* `$PROVIDER_ID`: The provider ID.
The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).
#### Using External Account Authorized User workforce credentials
[External account authorized user credentials](https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#browser-based-sign-in) allow you to sign in with a web browser to an external identity provider account via the
Expand Down Expand Up @@ -842,6 +929,45 @@ body: |-
You can now [use the Auth library](#using-external-identities) to call Google Cloud
resources from an OIDC or SAML provider.
### Accessing resources from an OIDC or SAML2.0 identity provider using a custom supplier
If you want to use OIDC or SAML2.0 that cannot be retrieved using methods supported natively by this library,
a custom SubjectTokenSupplier implementation may be specified when creating an identity pool client. The supplier must
return a valid, unexpired subject token when called by the GCP credential.
Note that the client does not cache the returned subject token, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.
```ts
class CustomSupplier implements SubjectTokenSupplier {
async getSubjectToken(
context: ExternalAccountSupplierContext
): Promise<string> {
const audience = context.audience;
const subjectTokenType = context.subjectTokenType;
// Return a valid subject token for the requested audience and subject token type.
}
}
const clientOptions = {
audience: '//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type.
subject_token_supplier: new CustomSupplier() // Set the custom supplier.
}
const client = new CustomSupplier(clientOptions);
```
Where the audience is: `//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`
Where the following variables need to be substituted:
* `WORKFORCE_POOL_ID`: The worforce pool ID.
* `$PROVIDER_ID`: The provider ID.
and the workforce pool user project is the project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#use_configuration_files_for_sign-in).
### Using External Identities
External identities (AWS, Azure and OIDC-based providers) can be used with `Application Default Credentials`.
Expand Down
126 changes: 126 additions & 0 deletions README.md
View file
Expand Up @@ -400,6 +400,55 @@ The gcloud create-cred-config command will be updated to support this soon.

You can now [start using the Auth library](#using-external-identities) to call Google Cloud resources from AWS.

### Accessing resources from AWS using a custom AWS security credentials supplier.

In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed:
- A workload identity pool needs to be created.
- AWS needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS).
- Permission to impersonate a service account needs to be granted to the external identity.

Follow the detailed [instructions](https://cloud.google.com/iam/docs/access-resources-aws) on how to configure workload identity federation from AWS.

If you want to use AWS security credentials that cannot be retrieved using methods supported natively by this library,
a custom AwsSecurityCredentialsSupplier implementation may be specified when creating an AWS client. The supplier must
return valid, unexpired AWS security credentials when called by the GCP credential.

Note that the client does not cache the returned AWS security credentials, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.

```ts
class AwsSupplier implements AwsSecurityCredentialsSupplier {
async getAwsRegion(context: ExternalAccountSupplierContext): Promise<string> {
// Return the current AWS region, i.e. 'us-east-2'.
}

async getAwsSecurityCredentials(
context: ExternalAccountSupplierContext
): Promise<AwsSecurityCredentials> {
const audience = context.audience;
// Return valid AWS security credentials for the requested audience.
}
}

const clientOptions = {
audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request', // Set the subject token type.
aws_security_credentials_supplier: new AwsSupplier() // Set the custom supplier.
}

const client = new AwsClient(clientOptions);
```

Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is: `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`

Where the following variables need to be substituted:

* `$PROJECT_NUMBER`: The Google Cloud project number.
* `$WORKLOAD_POOL_ID`: The workload pool ID.
* `$PROVIDER_ID`: The provider ID.


The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).

### Access resources from Microsoft Azure

In order to access Google Cloud resources from Microsoft Azure, the following requirements are needed:
Expand Down Expand Up @@ -508,6 +557,44 @@ Where the following variables need to be substituted:
- `$URL_TO_GET_OIDC_TOKEN`: The URL of the local server endpoint to call to retrieve the OIDC token.
- `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`.

### Accessing resources from an OIDC or SAML2.0 identity provider using a custom supplier

If you want to use OIDC or SAML2.0 that cannot be retrieved using methods supported natively by this library,
a custom SubjectTokenSupplier implementation may be specified when creating an identity pool client. The supplier must
return a valid, unexpired subject token when called by the GCP credential.

Note that the client does not cache the returned subject token, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.

```ts
class CustomSupplier implements SubjectTokenSupplier {
async getSubjectToken(
context: ExternalAccountSupplierContext
): Promise<string> {
const audience = context.audience;
const subjectTokenType = context.subjectTokenType;
// Return a valid subject token for the requested audience and subject token type.
}
}

const clientOptions = {
audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type.
subject_token_supplier: new CustomSupplier() // Set the custom supplier.
}

const client = new CustomSupplier(clientOptions);
```

Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is: `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`

Where the following variables need to be substituted:

* `$PROJECT_NUMBER`: The Google Cloud project number.
* `$WORKLOAD_POOL_ID`: The workload pool ID.
* `$PROVIDER_ID`: The provider ID.

The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).

#### Using External Account Authorized User workforce credentials

[External account authorized user credentials](https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#browser-based-sign-in) allow you to sign in with a web browser to an external identity provider account via the
Expand Down Expand Up @@ -886,6 +973,45 @@ credentials unless they do not meet your specific requirements.
You can now [use the Auth library](#using-external-identities) to call Google Cloud
resources from an OIDC or SAML provider.

### Accessing resources from an OIDC or SAML2.0 identity provider using a custom supplier

If you want to use OIDC or SAML2.0 that cannot be retrieved using methods supported natively by this library,
a custom SubjectTokenSupplier implementation may be specified when creating an identity pool client. The supplier must
return a valid, unexpired subject token when called by the GCP credential.

Note that the client does not cache the returned subject token, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.

```ts
class CustomSupplier implements SubjectTokenSupplier {
async getSubjectToken(
context: ExternalAccountSupplierContext
): Promise<string> {
const audience = context.audience;
const subjectTokenType = context.subjectTokenType;
// Return a valid subject token for the requested audience and subject token type.
}
}

const clientOptions = {
audience: '//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type.
subject_token_supplier: new CustomSupplier() // Set the custom supplier.
}

const client = new CustomSupplier(clientOptions);
```

Where the audience is: `//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`

Where the following variables need to be substituted:

* `WORKFORCE_POOL_ID`: The worforce pool ID.
* `$PROVIDER_ID`: The provider ID.

and the workforce pool user project is the project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).

The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#use_configuration_files_for_sign-in).

### Using External Identities

External identities (AWS, Azure and OIDC-based providers) can be used with `Application Default Credentials`.
Expand Down

0 comments on commit c680b5d

Please sign in to comment.