# keyring-gcloud
A keyring backend for Google Cloud Platform.
## Installation
We recommend using [uv](https://github.com/astral-sh/uv) to install this keyring
backend.
```bash
uv tool install keyring --with keyring-gcloud
```
## How it works
This backend does not store any credentials by itself. It will choose a
storage-backend by looking at all viable backends and choose the one with the
highest priority. It works by intercepting invocations of `keyring get|set`. A
`get` operation that is intercepted works like this:
1. Attempt to get the value from the storage backend
2. Decode this value as if it was written by **this backend**
1. If decoding successful, check the expiry of the token
1. If not expired, return the token.
2. If decoding unsuccessful, use google-auth to fetch a new token (similar
to doing `gcloud auth print-access-token`)
1. Store the new token in the storage backend
2. Return the new token
A `set` operation is simpler. It will just prepend an expiry of 1 hour to the
supplied token, encode these two values and store them in the storage backend.
## Usage
There are two ways to use this backend:
### 1: Via the `keyring` command line parameters:
AKA the "I'll use it on-demand, thank you very much" method.
```bash
export KEYRING_GCLOUD_ON=1_or_yes_or_any_string_really
keyring --keyring-backend keyring_gcloud.GoogleCloudKeyring <...>
```
The env variable `KEYRING_GCLOUD_ON` will make this backend intercept any
invocation.
### 2: Via the keyring configuration file:
In the keyring configuration file, add the following:
```toml
[backend]
default-keyring=keyring_gcloud.GoogleCloudKeyring
```
This will make `keyring` use the `GoogleCloudKeyring` backend on all calls to
`keyring get foo bar` (regardless of any `--keyring-backend` parameter). This
has some risk, since if you were to run
```bash
keyring set some-website foo@example.com mypassword
```
it is unlikely that you would want `mypassword` to have an expiry of 1 hour. To
lower this risk, you should **unset** the `KEYRING_GCLOUD_ON` environment
variable. When that env variable is **not set**, the backend only intercepts if
the `username` for the request matches `KEYRING_GCLOUD_USERNAME` (default
`oauth2accesstoken`).
So a call like
```bash
keyring get https://private-pypi.example.com/simple/ oauth2accesstoken
```
would be intercepted. Python tooling sometimes use keyring to fetch credentials
for private registries. `poetry` is an example of a service that does this with
`oauth2accesstoken` as the username). `uv` can use keyring if
`[[tool.uv.index]]` is set to a private registry and the environment variable
`UV_KEYRING_PROVIDER` is set to `subprocess`.
Raw data
{
"_id": null,
"home_page": null,
"name": "keyring-gcloud",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "keyring, gcloud, google cloud",
"author": "Tor Arvid Lund",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2f/50/f4ad1863436aba7cc3df87b4b4a099c0c2a9ed6a9a81847a9e9a3b534bb8/keyring_gcloud-0.1.3.tar.gz",
"platform": null,
"description": "# keyring-gcloud\n\nA keyring backend for Google Cloud Platform.\n\n## Installation\n\nWe recommend using [uv](https://github.com/astral-sh/uv) to install this keyring\nbackend.\n\n```bash\nuv tool install keyring --with keyring-gcloud\n```\n\n## How it works\n\nThis backend does not store any credentials by itself. It will choose a\nstorage-backend by looking at all viable backends and choose the one with the\nhighest priority. It works by intercepting invocations of `keyring get|set`. A\n`get` operation that is intercepted works like this:\n\n1. Attempt to get the value from the storage backend\n2. Decode this value as if it was written by **this backend**\n 1. If decoding successful, check the expiry of the token\n 1. If not expired, return the token.\n 2. If decoding unsuccessful, use google-auth to fetch a new token (similar\n to doing `gcloud auth print-access-token`)\n 1. Store the new token in the storage backend\n 2. Return the new token\n\nA `set` operation is simpler. It will just prepend an expiry of 1 hour to the\nsupplied token, encode these two values and store them in the storage backend.\n\n## Usage\n\nThere are two ways to use this backend:\n\n### 1: Via the `keyring` command line parameters:\n\nAKA the \"I'll use it on-demand, thank you very much\" method.\n\n```bash\nexport KEYRING_GCLOUD_ON=1_or_yes_or_any_string_really\nkeyring --keyring-backend keyring_gcloud.GoogleCloudKeyring <...>\n```\n\nThe env variable `KEYRING_GCLOUD_ON` will make this backend intercept any\ninvocation.\n\n### 2: Via the keyring configuration file:\n\nIn the keyring configuration file, add the following:\n\n```toml\n[backend]\ndefault-keyring=keyring_gcloud.GoogleCloudKeyring\n```\n\nThis will make `keyring` use the `GoogleCloudKeyring` backend on all calls to\n`keyring get foo bar` (regardless of any `--keyring-backend` parameter). This\nhas some risk, since if you were to run\n\n```bash\nkeyring set some-website foo@example.com mypassword\n```\n\nit is unlikely that you would want `mypassword` to have an expiry of 1 hour. To\nlower this risk, you should **unset** the `KEYRING_GCLOUD_ON` environment\nvariable. When that env variable is **not set**, the backend only intercepts if\nthe `username` for the request matches `KEYRING_GCLOUD_USERNAME` (default\n`oauth2accesstoken`).\n\nSo a call like\n\n```bash\nkeyring get https://private-pypi.example.com/simple/ oauth2accesstoken\n```\n\nwould be intercepted. Python tooling sometimes use keyring to fetch credentials\nfor private registries. `poetry` is an example of a service that does this with\n`oauth2accesstoken` as the username). `uv` can use keyring if\n`[[tool.uv.index]]` is set to a private registry and the environment variable\n`UV_KEYRING_PROVIDER` is set to `subprocess`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A keyring backend for Google Cloud Platform",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/torarvid/keyring-gcloud/issues",
"Homepage": "https://github.com/torarvid/keyring-gcloud"
},
"split_keywords": [
"keyring",
" gcloud",
" google cloud"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "894f832b56b50ba57c7b07daf33700cb41cdf5cff49046d0d57025e5f79a30ac",
"md5": "4cfadde8b4e40a8b17ae4d7f27debf2c",
"sha256": "911247023e9700df38c0f051e00646296d561d0229bce242b32e8367116474eb"
},
"downloads": -1,
"filename": "keyring_gcloud-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4cfadde8b4e40a8b17ae4d7f27debf2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 5175,
"upload_time": "2024-10-18T10:35:06",
"upload_time_iso_8601": "2024-10-18T10:35:06.011752Z",
"url": "https://files.pythonhosted.org/packages/89/4f/832b56b50ba57c7b07daf33700cb41cdf5cff49046d0d57025e5f79a30ac/keyring_gcloud-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2f50f4ad1863436aba7cc3df87b4b4a099c0c2a9ed6a9a81847a9e9a3b534bb8",
"md5": "0a5000a7ec86c85859777d63bab51d51",
"sha256": "c12a1cd8cee95d2af36b19dc60cef3457b39b79a4aa656590e0c32696e8e52c2"
},
"downloads": -1,
"filename": "keyring_gcloud-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "0a5000a7ec86c85859777d63bab51d51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 4951,
"upload_time": "2024-10-18T10:35:08",
"upload_time_iso_8601": "2024-10-18T10:35:08.495124Z",
"url": "https://files.pythonhosted.org/packages/2f/50/f4ad1863436aba7cc3df87b4b4a099c0c2a9ed6a9a81847a9e9a3b534bb8/keyring_gcloud-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-18 10:35:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "torarvid",
"github_project": "keyring-gcloud",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "keyring-gcloud"
}
JSON
