{"id":20206134,"url":"https://github.com/requests/requests-kerberos","last_synced_at":"2025-05-15T04:04:20.309Z","repository":{"id":5509783,"uuid":"6710117","full_name":"requests/requests-kerberos","owner":"requests","description":"An authentication handler for using Kerberos with Python Requests.","archived":false,"fork":false,"pushed_at":"2024-06-03T23:18:59.000Z","size":190,"stargazers_count":297,"open_issues_count":12,"forks_count":100,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-05-15T00:04:00.821Z","etag":null,"topics":["kerberos-authentication","python","python-requests"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/requests.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-11-15T19:22:30.000Z","updated_at":"2025-05-08T08:23:16.000Z","dependencies_parsed_at":"2024-06-18T12:30:41.715Z","dependency_job_id":"a710ae54-4c6e-4123-802d-e46bddef302e","html_url":"https://github.com/requests/requests-kerberos","commit_stats":{"total_commits":143,"total_committers":34,"mean_commits":4.205882352941177,"dds":0.7902097902097902,"last_synced_commit":"3f672cf7d175d7c073e3a52eeb979e33930330ee"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/requests%2Frequests-kerberos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/requests%2Frequests-kerberos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/requests%2Frequests-kerberos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/requests%2Frequests-kerberos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/requests","download_url":"https://codeload.github.com/requests/requests-kerberos/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270640,"owners_count":22042858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kerberos-authentication","python","python-requests"],"created_at":"2024-11-14T05:21:30.823Z","updated_at":"2025-05-15T04:04:20.281Z","avatar_url":"https://github.com/requests.png","language":"Python","readme":"requests Kerberos/GSSAPI authentication library\n===============================================\n\n.. image:: https://github.com/requests/requests-kerberos/actions/workflows/ci.yml/badge.svg\n    :target: https://github.com/requests/requests-kerberos/actions/workflows/ci.yml\n\nRequests is an HTTP library, written in Python, for human beings. This library\nadds optional Kerberos/GSSAPI authentication support and supports mutual\nauthentication. Basic GET usage:\n\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth\n    \u003e\u003e\u003e r = requests.get(\"http://example.org\", auth=HTTPKerberosAuth())\n    ...\n\nThe entire ``requests.api`` should be supported.\n\nSetup\n-----\n\nBefore installing this module, the underlying Kerberos C libraries and Python\ndevelopment headers need to be installed. An example of how to do this for\nsome Linux distributions is shown below:\n\n.. code-block:: bash\n\n    # For Debian based distros\n    apt-get install gcc python3-dev libkrb5-dev\n\n    # For EL based distros\n    dnf install gcc python3-devel krb5-devel\n\nThe names of the packages may vary across the distribution so use this as a\ngeneral guide. MacOS and Windows users should not need these development\nlibraries as the underlying Kerberos Python module for those platforms are\nprovided as a wheel and the C library is already preinstalled.\n\nWhile it is possible to use Kerberos authentication with an explicit\n``principal`` and ``password`` as an arg to ``HTTPKerberosAuth``, it is\nrecommended to use an existing credential cache to store the credentials\ninstead. The credential cache can store a Kerberos Ticket-Granting Ticket\n(``TGT``) which is then used for authentication when no ``password`` is given\nto ``HTTPKerberosAuth``. The credential cache can store a ``TGT`` by using the\n``kinit`` command and ``klist`` can be used to view the contents of the cache.\nThe environment variable ``KRB5CCNAME`` can be used to specify the location of\na custom credential cache.\n\nAuthentication Failures\n-----------------------\n\nClient authentication failures will be communicated to the caller by returning\nthe 401 response. A 401 response may also come from an expired Ticket-Granting\nTicket.\n\nMutual Authentication\n---------------------\n\nREQUIRED\n^^^^^^^^\n\nBy default, ``HTTPKerberosAuth`` will require mutual authentication from the\nserver, and if a server emits a non-error response which cannot be\nauthenticated, a ``requests_kerberos.errors.MutualAuthenticationError`` will\nbe raised. If a server emits an error which cannot be authenticated, it will\nbe returned to the user but with its contents and headers stripped. If the\nresponse content is more important than the need for mutual auth on errors,\n(eg, for certain WinRM calls) the stripping behavior can be suppressed by\nsetting ``sanitize_mutual_error_response=False``:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth, REQUIRED\n    \u003e\u003e\u003e kerberos_auth = HTTPKerberosAuth(mutual_authentication=REQUIRED, sanitize_mutual_error_response=False)\n    \u003e\u003e\u003e r = requests.get(\"https://windows.example.org/wsman\", auth=kerberos_auth)\n    ...\n\n\nOPTIONAL\n^^^^^^^^\n\nIf you'd prefer to not require mutual authentication, you can set your\npreference when constructing your ``HTTPKerberosAuth`` object:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth, OPTIONAL\n    \u003e\u003e\u003e kerberos_auth = HTTPKerberosAuth(mutual_authentication=OPTIONAL)\n    \u003e\u003e\u003e r = requests.get(\"http://example.org\", auth=kerberos_auth)\n    ...\n\nThis will cause ``requests_kerberos`` to attempt mutual authentication if the\nserver advertises that it supports it, and cause a failure if authentication\nfails, but not if the server does not support it at all.\n\nDISABLED\n^^^^^^^^\n\nWhile we don't recommend it, if you'd prefer to never attempt mutual\nauthentication, you can do that as well:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth, DISABLED\n    \u003e\u003e\u003e kerberos_auth = HTTPKerberosAuth(mutual_authentication=DISABLED)\n    \u003e\u003e\u003e r = requests.get(\"http://example.org\", auth=kerberos_auth)\n    ...\n\nPreemptive Authentication\n-------------------------\n\n``HTTPKerberosAuth`` can be forced to preemptively initiate the Kerberos\nGSS exchange and present a Kerberos ticket on the initial request (and all\nsubsequent). By default, authentication only occurs after a\n``401 Unauthorized`` response containing a Kerberos or Negotiate challenge\nis received from the origin server. This can cause mutual authentication\nfailures for hosts that use a persistent connection (eg, Windows/WinRM), as\nno Kerberos challenges are sent after the initial auth handshake. This\nbehavior can be altered by setting  ``force_preemptive=True``:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth, REQUIRED\n    \u003e\u003e\u003e kerberos_auth = HTTPKerberosAuth(mutual_authentication=REQUIRED, force_preemptive=True)\n    \u003e\u003e\u003e r = requests.get(\"https://windows.example.org/wsman\", auth=kerberos_auth)\n    ...\n\nHostname Override\n-----------------\n\nIf communicating with a host whose DNS name doesn't match its\nkerberos hostname (eg, behind a content switch or load balancer),\nthe hostname used for the Kerberos GSS exchange can be overridden by\nsetting the ``hostname_override`` arg:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth, REQUIRED\n    \u003e\u003e\u003e kerberos_auth = HTTPKerberosAuth(hostname_override=\"internalhost.local\")\n    \u003e\u003e\u003e r = requests.get(\"https://externalhost.example.org/\", auth=kerberos_auth)\n    ...\n\nExplicit Principal\n------------------\n\n``HTTPKerberosAuth`` normally uses the default principal (ie, the user for\nwhom you last ran ``kinit`` or ``kswitch``, or an SSO credential if\napplicable). However, an explicit principal can be specified, which will\ncause Kerberos to look for a matching credential cache for the named user.\nThis feature depends on OS support for collection-type credential caches.\nAn explicit principal can be specified with the ``principal`` arg:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth, REQUIRED\n    \u003e\u003e\u003e kerberos_auth = HTTPKerberosAuth(principal=\"user@REALM\")\n    \u003e\u003e\u003e r = requests.get(\"http://example.org\", auth=kerberos_auth)\n    ...\n\nPassword Authentication\n-----------------------\n\n``HTTPKerberosAuth`` can be used with an explicit principal and password\ninstead of using a credential stored in the credential cache. An explicit\nusername and password can be specified with the ``principal`` and ``password``\narg respectively:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth, REQUIRED\n    \u003e\u003e\u003e kerberos_auth = HTTPKerberosAuth(\n    ...     principal=\"user@REALM\",\n    ...     password=\"SecretPassword\",\n    ...)\n    \u003e\u003e\u003e r = requests.get(\"http://example.org\", auth=kerberos_auth)\n\nWhen specifing a custom principal and password, the underlying Kerberos\nlibrary will request a TGT from the KDC before using that TGT to retrieve the\nservice ticket for authentication.\n\nDelegation\n----------\n\n``requests_kerberos`` supports credential delegation (``GSS_C_DELEG_FLAG``).\nTo enable delegation of credentials to a server that requests delegation, pass\n``delegate=True`` to ``HTTPKerberosAuth``:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import requests\n    \u003e\u003e\u003e from requests_kerberos import HTTPKerberosAuth\n    \u003e\u003e\u003e r = requests.get(\"http://example.org\", auth=HTTPKerberosAuth(delegate=True))\n    ...\n\nBe careful to only allow delegation to servers you trust as they will be able\nto impersonate you using the delegated credentials.\n\nLogging\n-------\n\nThis library makes extensive use of Python's logging facilities.\n\nLog messages are logged to the ``requests_kerberos`` and\n``requests_kerberos.kerberos_`` named loggers.\n\nIf you are having difficulty we suggest you configure logging. Issues with the\nunderlying kerberos libraries will be made apparent. Additionally, copious debug\ninformation is made available which may assist in troubleshooting if you\nincrease your log level all the way up to debug.\n\nChannel Binding\n---------------\n\nSince ``v0.12.0`` this library automatically attempts to bind the\nauthentication token with the channel binding data when connecting over a TLS\nconnection. Channel Binding is also known as Extended Protection for\nAuthentication (``EPA``) from Microsoft. This should be ignored by servers\nwhich do not implement support for CB but in the rare case this still fails it\ncan be disabled by setting ``send_cbt=False``.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frequests%2Frequests-kerberos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frequests%2Frequests-kerberos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frequests%2Frequests-kerberos/lists"}