Credential store plugin for HTTPie
==================================
HTTPie Credential Store is an `HTTPie`_ authentication plugin that looks
for credentials using a given URL and attaches them to the ongoing HTTP
request. That said, you don't need to memorize and/or look for
tokens/username/passwords anymore. Simply add them to the credential
store and everything else will be done for you by this plugin. It goes
without saying that this plugin supports various secured secret storages
such as system keychains or password managers (see keychain providers).
Eager to get started? Just start with installing!
.. code:: bash
$ python3 -m pip install httpie-credential-store
Usage
-----
.. note:: Please, do not forget to activate the plugin by invoking
``http`` with ``-A creds`` option.
Once installed, the plugin will look for credentials in the credential
file. The credential file is stored in HTTPie configuration directory.
So on Linux/macOS, it will look for ``~/.httpie/credentials.json``,
while on Windows - for ``%APPDATA%\httpie\credentials.json``. The
credential file will not be created for you, you're fully responsible
for creating one.
By its nature, the credentials file is a JSON array of credential
records. Each credential record consists of the following properties:
* ``url`` (*required*) is a regular expression pattern that is used to
map credential record to the ongoing HTTP request. I.e. if the regular
expression matches URL of the ongoing HTTP request, credentials of
matched record must be attached.
* ``auth`` (*required*) is an authentication provider to use for a given
record. The provider will be used to attach credentials to the ongoing
HTTP request if the record is matched.
* ``id`` (*optional*) is unique identifier of the credential record that
can be used to solve ambiguousness between two or more matched
credential records. By using ``id`` one may achieve support of
multiple accounts for the same service.
Example:
.. code:: json
[
{
"url": "api.github.com",
"auth": {
"provider": "token",
"token": "your-github-oauth-token",
"scheme": "token"
}
},
{
"id": "bots",
"url": "api.github.com",
"auth": {
"provider": "token",
"token": "bots-github-oauth-token",
"scheme": "token"
}
}
]
The example above assumes you store your secrets unencrypted in the
credential file. Despite enforcing you to set sole access permissions
for the credential file, it's not secured and, hence, not recommended.
HTTPie Credential Store plugin can pull secrets and other sensitive
information out from password managers or system keychains. For
instance, you can pull your token from the `password store`_ by using
the following credential record:
.. code:: json
[
{
"url": "api.github.com",
"auth": {
"provider": "token",
"scheme": "token",
"token": {
"keychain": "password-store",
"name": "github.com/ikalnytskyi/token"
}
}
}
]
Once the credential store is filled, you're ready to use the plugin at
your will. In order to activate the plugin, you must pass ``-A creds``
or ``-A credential-store`` to ``http`` executable.
.. code:: bash
$ http -A creds https://api.github.com
Optionally, you can provide an ID of the credential record to use by
passing ``-a`` argument.
.. code:: bash
$ http -A creds -a bots https://api.github.com
Authentication providers
------------------------
HTTPie Credential Store comes with the following authentication
providers out of box.
``basic``
.........
The 'Basic' HTTP authentication scheme as defined in :RFC:`7617`.
Transmits credentials as username/password pairs, encoded using Base64.
.. code:: json
{
"provider": "basic",
"username": "ikalnytskyi",
"password": "p@ss"
}
where
* ``username`` is a username to authenticate
* ``password`` is a password of the authenticating user
``digest``
..........
The 'Digest' HTTP authentication scheme as defined in :RFC:`2617`. It
applies a hash function to the username and password before sending them
over the network.
.. code:: json
{
"provider": "digest",
"username": "ikalnytskyi",
"password": "p@ss"
}
where
* ``username`` is a username to authenticate
* ``password`` is a password of the authenticating user
``token``
.........
The 'Token' HTTP authentication scheme (also called 'Bearer') transmits
token in the ``Authorization`` HTTP header.
.. code:: json
{
"provider": "token",
"token": "t0k3n",
"scheme": "JWT"
}
where
* ``token`` is a token of the authenticating user
* ``scheme`` (optional, default: "Bearer") is an authenticating scheme
``header``
..........
The 'Header' HTTP authentication is not exactly an authentication
scheme. It's rather a way to pass any free-formed HTTP header with
secret or not.
.. code:: json
{
"provider": "header",
"name": "X-Extra-Key",
"value": "k3y"
}
where
* ``name`` is an HTTP header name to use
* ``value`` is an HTTP header value to pass
``multiple``
............
This is a fake authentication scheme even in terms of this plugin. It
does no auth but chains and applies one or more providers
simultaneously. It's something you will (likely) never use.
.. code:: json
{
"provider": "multiple",
"providers": [
{
"provider": "token",
"token": "t0k3n"
},
{
"provider": "header",
"name": "X-Extra-Key",
"value": "k3y"
}
]
}
where
* ``providers`` is a list of auth providers to use simultaneously
Keychain providers
------------------
The plugin supports a bunch of keychains that can be used to pull
secrets from secured storage.
``shell``
.........
Shell provider is nothing more but a mere shell command to execute. The
command must return a secret to the plugin via standard output stream.
This is a universal approach that can be used to glue together various
unsupported password managers and/or keychains.
Example:
.. code:: json
{
"keychain": "shell",
"command": "cat ~/path/to/secret | tr -d '\n'"
}
where
* ``command`` is a shell command to execute
``system``
..........
System provider, as the name suggests, use your system keychain to pull
secrets from. It may be **KWallet**, **GNOME Keyring**, **macOS
Keychain** or even **Windows Credential Locker**.
Example:
.. code:: json
{
"keychain": "system",
"service": "github",
"username": "ikalnytskyi"
}
where
* ``service`` is a service to pull data for
* ``username`` is a username for that service to pull data for
``password-store``
..................
Password store provider is a bridge between this plugin and the
`password store`_. It invokes ``pass`` on your system and pulls the
secret from the first line of the stored record (normally password).
Example:
.. code:: json
{
"keychain": "password-store",
"name": "github.com/ikalnytskyi"
}
where
* ``name`` is a pass name in terms of the password store
FAQ
---
* **Q**: How to learn which credentials have been attached to the request?
**A**: Unfortunately, due to late credentials binding, it's impossible
to learn which credentials have been used by running ``http --debug``
command. Nevertheless, one can check amends made by auth providers by
inspect HTTP headers transmitted within the request by passing ``-v``
argument to HTTPie: ``http -v``.
.. _HTTPie: https://httpie.org/
.. _password store: https://www.passwordstore.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/ikalnytskyi/httpie-credential-store",
"name": "httpie-credential-store",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "httpie, credential, store, keychain, plugin, auth",
"author": "Ihor Kalnytskyi",
"author_email": "ihor@kalnytskyi.com",
"download_url": "https://files.pythonhosted.org/packages/16/e3/f97af71455ecf2418c33496389a12756999877a87b49f15405d49ce18d78/httpie_credential_store-3.1.0.tar.gz",
"platform": null,
"description": "Credential store plugin for HTTPie\n==================================\n\nHTTPie Credential Store is an `HTTPie`_ authentication plugin that looks\nfor credentials using a given URL and attaches them to the ongoing HTTP\nrequest. That said, you don't need to memorize and/or look for\ntokens/username/passwords anymore. Simply add them to the credential\nstore and everything else will be done for you by this plugin. It goes\nwithout saying that this plugin supports various secured secret storages\nsuch as system keychains or password managers (see keychain providers).\n\nEager to get started? Just start with installing!\n\n.. code:: bash\n\n $ python3 -m pip install httpie-credential-store\n\n\nUsage\n-----\n\n.. note:: Please, do not forget to activate the plugin by invoking\n ``http`` with ``-A creds`` option.\n\nOnce installed, the plugin will look for credentials in the credential\nfile. The credential file is stored in HTTPie configuration directory.\nSo on Linux/macOS, it will look for ``~/.httpie/credentials.json``,\nwhile on Windows - for ``%APPDATA%\\httpie\\credentials.json``. The\ncredential file will not be created for you, you're fully responsible\nfor creating one.\n\nBy its nature, the credentials file is a JSON array of credential\nrecords. Each credential record consists of the following properties:\n\n* ``url`` (*required*) is a regular expression pattern that is used to\n map credential record to the ongoing HTTP request. I.e. if the regular\n expression matches URL of the ongoing HTTP request, credentials of\n matched record must be attached.\n\n* ``auth`` (*required*) is an authentication provider to use for a given\n record. The provider will be used to attach credentials to the ongoing\n HTTP request if the record is matched.\n\n* ``id`` (*optional*) is unique identifier of the credential record that\n can be used to solve ambiguousness between two or more matched\n credential records. By using ``id`` one may achieve support of\n multiple accounts for the same service.\n\nExample:\n\n.. code:: json\n\n [\n {\n \"url\": \"api.github.com\",\n \"auth\": {\n \"provider\": \"token\",\n \"token\": \"your-github-oauth-token\",\n \"scheme\": \"token\"\n }\n },\n {\n \"id\": \"bots\",\n \"url\": \"api.github.com\",\n \"auth\": {\n \"provider\": \"token\",\n \"token\": \"bots-github-oauth-token\",\n \"scheme\": \"token\"\n }\n }\n ]\n\nThe example above assumes you store your secrets unencrypted in the\ncredential file. Despite enforcing you to set sole access permissions\nfor the credential file, it's not secured and, hence, not recommended.\nHTTPie Credential Store plugin can pull secrets and other sensitive\ninformation out from password managers or system keychains. For\ninstance, you can pull your token from the `password store`_ by using\nthe following credential record:\n\n.. code:: json\n\n [\n {\n \"url\": \"api.github.com\",\n \"auth\": {\n \"provider\": \"token\",\n \"scheme\": \"token\",\n \"token\": {\n \"keychain\": \"password-store\",\n \"name\": \"github.com/ikalnytskyi/token\"\n }\n }\n }\n ]\n\nOnce the credential store is filled, you're ready to use the plugin at\nyour will. In order to activate the plugin, you must pass ``-A creds``\nor ``-A credential-store`` to ``http`` executable.\n\n.. code:: bash\n\n $ http -A creds https://api.github.com\n\nOptionally, you can provide an ID of the credential record to use by\npassing ``-a`` argument.\n\n.. code:: bash\n\n $ http -A creds -a bots https://api.github.com\n\n\nAuthentication providers\n------------------------\n\nHTTPie Credential Store comes with the following authentication\nproviders out of box.\n\n\n``basic``\n.........\n\nThe 'Basic' HTTP authentication scheme as defined in :RFC:`7617`.\nTransmits credentials as username/password pairs, encoded using Base64.\n\n.. code:: json\n\n {\n \"provider\": \"basic\",\n \"username\": \"ikalnytskyi\",\n \"password\": \"p@ss\"\n }\n\nwhere\n\n* ``username`` is a username to authenticate\n* ``password`` is a password of the authenticating user\n\n\n``digest``\n..........\n\nThe 'Digest' HTTP authentication scheme as defined in :RFC:`2617`. It\napplies a hash function to the username and password before sending them\nover the network.\n\n.. code:: json\n\n {\n \"provider\": \"digest\",\n \"username\": \"ikalnytskyi\",\n \"password\": \"p@ss\"\n }\n\nwhere\n\n* ``username`` is a username to authenticate\n* ``password`` is a password of the authenticating user\n\n\n``token``\n.........\n\nThe 'Token' HTTP authentication scheme (also called 'Bearer') transmits\ntoken in the ``Authorization`` HTTP header.\n\n.. code:: json\n\n {\n \"provider\": \"token\",\n \"token\": \"t0k3n\",\n \"scheme\": \"JWT\"\n }\n\nwhere\n\n* ``token`` is a token of the authenticating user\n* ``scheme`` (optional, default: \"Bearer\") is an authenticating scheme\n\n\n``header``\n..........\n\nThe 'Header' HTTP authentication is not exactly an authentication\nscheme. It's rather a way to pass any free-formed HTTP header with\nsecret or not.\n\n.. code:: json\n\n {\n \"provider\": \"header\",\n \"name\": \"X-Extra-Key\",\n \"value\": \"k3y\"\n }\n\nwhere\n\n* ``name`` is an HTTP header name to use\n* ``value`` is an HTTP header value to pass\n\n\n``multiple``\n............\n\nThis is a fake authentication scheme even in terms of this plugin. It\ndoes no auth but chains and applies one or more providers\nsimultaneously. It's something you will (likely) never use.\n\n.. code:: json\n\n {\n \"provider\": \"multiple\",\n \"providers\": [\n {\n \"provider\": \"token\",\n \"token\": \"t0k3n\"\n },\n {\n \"provider\": \"header\",\n \"name\": \"X-Extra-Key\",\n \"value\": \"k3y\"\n }\n ]\n }\n\nwhere\n\n* ``providers`` is a list of auth providers to use simultaneously\n\n\nKeychain providers\n------------------\n\nThe plugin supports a bunch of keychains that can be used to pull\nsecrets from secured storage.\n\n\n``shell``\n.........\n\nShell provider is nothing more but a mere shell command to execute. The\ncommand must return a secret to the plugin via standard output stream.\nThis is a universal approach that can be used to glue together various\nunsupported password managers and/or keychains.\n\nExample:\n\n.. code:: json\n\n {\n \"keychain\": \"shell\",\n \"command\": \"cat ~/path/to/secret | tr -d '\\n'\"\n }\n\nwhere\n\n* ``command`` is a shell command to execute\n\n\n\n``system``\n..........\n\nSystem provider, as the name suggests, use your system keychain to pull\nsecrets from. It may be **KWallet**, **GNOME Keyring**, **macOS\nKeychain** or even **Windows Credential Locker**.\n\nExample:\n\n.. code:: json\n\n {\n \"keychain\": \"system\",\n \"service\": \"github\",\n \"username\": \"ikalnytskyi\"\n }\n\nwhere\n\n* ``service`` is a service to pull data for\n* ``username`` is a username for that service to pull data for\n\n\n``password-store``\n..................\n\nPassword store provider is a bridge between this plugin and the\n`password store`_. It invokes ``pass`` on your system and pulls the\nsecret from the first line of the stored record (normally password).\n\nExample:\n\n.. code:: json\n\n {\n \"keychain\": \"password-store\",\n \"name\": \"github.com/ikalnytskyi\"\n }\n\nwhere\n\n* ``name`` is a pass name in terms of the password store\n\nFAQ\n---\n\n* **Q**: How to learn which credentials have been attached to the request?\n\n **A**: Unfortunately, due to late credentials binding, it's impossible\n to learn which credentials have been used by running ``http --debug``\n command. Nevertheless, one can check amends made by auth providers by\n inspect HTTP headers transmitted within the request by passing ``-v``\n argument to HTTPie: ``http -v``.\n\n\n.. _HTTPie: https://httpie.org/\n.. _password store: https://www.passwordstore.org/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "HTTPie: one auth to rule them all!",
"version": "3.1.0",
"project_urls": {
"Homepage": "https://github.com/ikalnytskyi/httpie-credential-store",
"Repository": "https://github.com/ikalnytskyi/httpie-credential-store"
},
"split_keywords": [
"httpie",
" credential",
" store",
" keychain",
" plugin",
" auth"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35889cd816c29e2b45b181b794de013bef200c5546d0a4e414e439703c7e81b7",
"md5": "fd6b3837ae34931ded1141e4c8b1eced",
"sha256": "16b5795b2942cc671f5fc96e47297862ec0c6e28445859fe8a80515a926f6cd3"
},
"downloads": -1,
"filename": "httpie_credential_store-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd6b3837ae34931ded1141e4c8b1eced",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 8428,
"upload_time": "2024-05-05T18:56:22",
"upload_time_iso_8601": "2024-05-05T18:56:22.978324Z",
"url": "https://files.pythonhosted.org/packages/35/88/9cd816c29e2b45b181b794de013bef200c5546d0a4e414e439703c7e81b7/httpie_credential_store-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16e3f97af71455ecf2418c33496389a12756999877a87b49f15405d49ce18d78",
"md5": "ac67ed2b7bb2a3041d4737fc0b2eca89",
"sha256": "c649140323a712212ebd4b7bc92fc762ae400cff56c5cc8b791f5244830ef1a1"
},
"downloads": -1,
"filename": "httpie_credential_store-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ac67ed2b7bb2a3041d4737fc0b2eca89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 6494,
"upload_time": "2024-05-05T18:56:24",
"upload_time_iso_8601": "2024-05-05T18:56:24.798158Z",
"url": "https://files.pythonhosted.org/packages/16/e3/f97af71455ecf2418c33496389a12756999877a87b49f15405d49ce18d78/httpie_credential_store-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-05 18:56:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ikalnytskyi",
"github_project": "httpie-credential-store",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "httpie-credential-store"
}
JSON
