diff --git a/CHANGELOG.md b/CHANGELOG.md index 2404b282e..53359b566 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ [1]: https://pypi.org/project/google-auth/#history +## [2.36.1](https://github.com/googleapis/google-auth-library-python/compare/v2.36.0...v2.36.1) (2024-11-08) + + +### Bug Fixes + +* Improve user guide for Impersonation and SA ([#1627](https://github.com/googleapis/google-auth-library-python/issues/1627)) ([656307d](https://github.com/googleapis/google-auth-library-python/commit/656307d40941d2b72bb41e15238ebabba5ab6f52)) + ## [2.36.0](https://github.com/googleapis/google-auth-library-python/compare/v2.35.0...v2.36.0) (2024-10-30) diff --git a/docs/user-guide.rst b/docs/user-guide.rst index e9ad000e5..3545a8a31 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -62,57 +62,6 @@ store service account private keys locally. .. _Google Cloud SDK: https://cloud.google.com/sdk -Service account private key files -+++++++++++++++++++++++++++++++++ - -A service account private key file can be used to obtain credentials for a -service account. You can create a private key using the `Credentials page of the -Google Cloud Console`_. Once you have a private key you can either obtain -credentials one of three ways: - -1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full - path to your service account private key file - - .. code-block:: bash - - $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json - - Then, use :ref:`application default credentials `. - :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS`` - environment variable before all other checks, so this will always use the - credentials you explicitly specify. - -2. Use :meth:`service_account.Credentials.from_service_account_file - `:: - - from google.oauth2 import service_account - - credentials = service_account.Credentials.from_service_account_file( - '/path/to/key.json') - - scoped_credentials = credentials.with_scopes( - ['https://www.googleapis.com/auth/cloud-platform']) - -3. Use :meth:`service_account.Credentials.from_service_account_info - `:: - - import json - - from google.oauth2 import service_account - - json_acct_info = json.loads(function_to_get_json_creds()) - credentials = service_account.Credentials.from_service_account_info( - json_acct_info) - - scoped_credentials = credentials.with_scopes( - ['https://www.googleapis.com/auth/cloud-platform']) - -.. warning:: Private keys must be kept secret. If you expose your private key it - is recommended to revoke it immediately from the Google Cloud Console. - -.. _Credentials page of the Google Cloud Console: - https://console.cloud.google.com/apis/credentials - Compute Engine, Container Engine, and the App Engine flexible environment +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -231,6 +180,7 @@ You can also use :class:`google_auth_oauthlib.flow.Flow` to perform the OAuth .. _requests-oauthlib: https://requests-oauthlib.readthedocs.io/en/latest/ + External credentials (Workload identity federation) +++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -981,7 +931,8 @@ Impersonated credentials ++++++++++++++++++++++++ Impersonated Credentials allows one set of credentials issued to a user or service account -to impersonate another. The source credentials must be granted +to impersonate a service account. Impersonation is the preferred way of using service account for +local development over downloading the service account key. The source credentials must be granted the "Service Account Token Creator" IAM role. :: from google.auth import impersonated_credentials @@ -1006,6 +957,63 @@ In the example above `source_credentials` does not have direct access to list bu in the target project. Using `ImpersonatedCredentials` will allow the source_credentials to assume the identity of a target_principal that does have access. +It is possible to provide a delegation chain through `delegates` paramter while +initializing the impersonated credential. Refer `create short lived credentials delegated`_ for more details on delegation chain. + +.. _create short lived credentials delegated: https://cloud.google.com/iam/docs/create-short-lived-credentials-delegated + + +Service account private key files ++++++++++++++++++++++++++++++++++ + +A service account private key file can be used to obtain credentials for a service account. If you are not +able to use any of the authentication methods listed above, you can create a private key using `Credentials page of the +Google Cloud Console`_. Once you have a private key you can obtain +credentials one of three ways: + +1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full + path to your service account private key file + + .. code-block:: bash + + $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json + + Then, use :ref:`application default credentials `. + :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS`` + environment variable before all other checks, so this will always use the + credentials you explicitly specify. + +2. Use :meth:`service_account.Credentials.from_service_account_file + `:: + + from google.oauth2 import service_account + + credentials = service_account.Credentials.from_service_account_file( + '/path/to/key.json') + + scoped_credentials = credentials.with_scopes( + ['https://www.googleapis.com/auth/cloud-platform']) + +3. Use :meth:`service_account.Credentials.from_service_account_info + `:: + + import json + + from google.oauth2 import service_account + + json_acct_info = json.loads(function_to_get_json_creds()) + credentials = service_account.Credentials.from_service_account_info( + json_acct_info) + + scoped_credentials = credentials.with_scopes( + ['https://www.googleapis.com/auth/cloud-platform']) + +.. warning:: Private keys must be kept secret. If you expose your private key it + is recommended to revoke it immediately from the Google Cloud Console. + +.. _Credentials page of the Google Cloud Console: + https://console.cloud.google.com/apis/credentials + Downscoped credentials ++++++++++++++++++++++ diff --git a/google/auth/version.py b/google/auth/version.py index 15dc37470..e5bf67c06 100644 --- a/google/auth/version.py +++ b/google/auth/version.py @@ -12,4 +12,4 @@ # See the License for the specific language governing permissions and # limitations under the License. -__version__ = "2.36.0" +__version__ = "2.36.1" diff --git a/system_tests/secrets.tar.enc b/system_tests/secrets.tar.enc index d0d4ce702..590ca713a 100644 Binary files a/system_tests/secrets.tar.enc and b/system_tests/secrets.tar.enc differ