feat: Custom Credential Supplier Documentation

[vverman]

Adding documentation for Custom Credential Suppliers.

Custom Credential Suppliers enable developers to securely integrate third-party authentication directly into the Google Cloud SDKs. Custom Credential Suppliers are primarily used to handle authentication in non-standard cloud environments.

The design and scopes for this are documented

Checklist

• I have followed Sample Guidelines from AUTHORING_GUIDE.MD
• README is updated to include all relevant information
• Tests pass: nox -s py-3.9 (see Test Environment Setup)
• Lint pass: nox -s lint (see Test Environment Setup)
• These samples need a new API enabled in testing projects to pass (let us know which ones)
• These samples need a new/updated env vars in testing projects set to run the system integration tests.
• This sample adds a new sample directory, and I updated the CODEOWNERS file with the codeowners for this sample
• This sample adds a new Product API, and I updated the Blunderbuss issue/PR auto-assigner with the codeowners for this sample
• Please merge this PR for me once it is approved

[snippet-bot]

Here is the summary of changes.

You are about to add 2 region tags.

• auth/custom-credentials/aws/snippets.py:14, tag auth_custom_credential_supplier_aws
• auth/custom-credentials/okta/snippets.py:14, tag auth_custom_credential_supplier_okta

---

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

• Refresh this comment

[gemini-code-assist]

Summary of Changes

Hello @vverman, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the authentication samples by adding support for Custom Credential Suppliers in Python. It provides practical examples and comprehensive documentation for integrating external identity providers like AWS and Okta with Google Cloud, facilitating secure access in hybrid or multi-cloud environments. The changes aim to make it easier for developers to leverage Workload Identity Federation with non-standard authentication sources.

Highlights

• New Custom Credential Supplier Samples: Introduced new Python samples demonstrating how to use custom credential suppliers for both AWS and Okta authentication with Google Cloud SDKs.
• AWS Integration: Added a sample that uses Boto3 as a custom supplier to bridge AWS credentials (e.g., from EKS IRSA) to Google Cloud Workload Identity, complete with local and containerized (EKS) running instructions.
• Okta Integration: Included a sample demonstrating how to use Okta's Client Credentials grant flow as a custom subject token supplier for Workload Identity Federation with GCP.
• Comprehensive Documentation: Each new sample comes with detailed READMEs covering setup, environment variables, and configuration steps for both the third-party identity provider (AWS/Okta) and Google Cloud.
• Testing Infrastructure: Accompanying unit and system tests, along with Nox configurations, have been added for both AWS and Okta custom credential supplier samples to ensure functionality and reliability.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces new samples for using custom credential suppliers with the Google Cloud Python SDK, specifically for AWS and Okta. The code is well-structured and includes good documentation and tests. My review includes suggestions to improve error handling by using more specific exceptions and directing error messages to stderr, which is a standard practice. I've also pointed out a few minor issues like missing newlines at the end of files and an opportunity to make the Okta supplier more flexible by not hardcoding the OAuth scope. These changes will enhance the robustness and reusability of the samples.

[gemini-code-assist]

It's a good practice for text files, including requirements.txt, to end with a newline character. This can prevent issues with some tools and file concatenations.

python-dotenv==1.1.1

[gemini-code-assist]

The Okta scope is hardcoded here. For better reusability, consider passing the scope(s) as an argument to the OktaClientCredentialsSupplier constructor. This would allow users of the class to specify the required scopes for their particular Okta application configuration without modifying the class source code.

[gemini-code-assist]

There are a couple of improvements we can make here:

1. Error messages should be printed to standard error (sys.stderr) instead of standard output. This is a standard practice for separating normal output from error diagnostics.
2. Catching a generic Exception is too broad and can hide bugs by catching unexpected errors (like KeyboardInterrupt). It's better to catch more specific exceptions that are expected from the authentication and request process, such as google.auth.exceptions.GoogleAuthError and requests.exceptions.HTTPError.

Suggested change

	if not all(
	[gcp_audience, gcs_bucket_name, okta_domain, okta_client_id, okta_client_secret]
	):
	print("Missing required environment variables.")
	return
	try:
	print(f"Retrieving metadata for bucket: {gcs_bucket_name}...")
	metadata = authenticate_with_okta_credentials(
	bucket_name=gcs_bucket_name,
	audience=gcp_audience,
	domain=okta_domain,
	client_id=okta_client_id,
	client_secret=okta_client_secret,
	impersonation_url=sa_impersonation_url,
	)
	print("--- SUCCESS! ---")
	print(json.dumps(metadata, indent=2))
	except Exception as e:
	print(f"Authentication or Request failed: {e}")
	if not all(
	[gcp_audience, gcs_bucket_name, okta_domain, okta_client_id, okta_client_secret]
	):
	print("Missing required environment variables.", file=sys.stderr)
	return
	try:
	print(f"Retrieving metadata for bucket: {gcs_bucket_name}...")
	metadata = authenticate_with_okta_credentials(
	bucket_name=gcs_bucket_name,
	audience=gcp_audience,
	domain=okta_domain,
	client_id=okta_client_id,
	client_secret=okta_client_secret,
	impersonation_url=sa_impersonation_url,
	)
	print("--- SUCCESS! ---")
	print(json.dumps(metadata, indent=2))
	except (exceptions.GoogleAuthError, requests.exceptions.HTTPError) as e:
	print(f"Authentication or Request failed: {e}", file=sys.stderr)

[iennae]

there are some refinements that could be done in the okta, but this looks fine.

I've addressed some improvements to speed up feedback to Iyer based on feedback from Siracusa. I also updated the README to be more in alignment with the standards set by DevSite for how we refer to things.

for folks who may be looking at this in the future, for context, we decided that there isn't a path for third-party samples currently so there is limited testing and that must be done manually. The owner of the samples has verified that the samples work as expected. This is also why the documentation is the README is much more extensive than for some samples.

[iennae]

apologies @vverman

I just noticed when fixing linting in okta, I realized that the GCS bucket code is not using the SDK there. Is it possible to use the SDK and send the credentials object from the supplier and then use the SDK and that would allow simplification with the bucket object metadata?