Metadata-Version: 2.1
Name: requests-auth
Version: 4.0.1
Summary: Easy Authentication for Requests
Home-page: https://github.com/Colin-b/requests_auth
Author: Colin Bounouar
Author-email: colin.bounouar.dev@gmail.com
Maintainer: Colin Bounouar
Maintainer-email: colin.bounouar.dev@gmail.com
License: MIT
Download-URL: https://pypi.org/project/requests-auth/
Description: # Easy Authentication for Requests #
        
        This module provides you authentication classes to be used with [`requests`][1].
        
        To use a specific authentication in combination with requests, use the [authentication parameter on `requests` module][2].
        
        ## OAuth 2 ##
        
        ### Authorization Code flow ###
        
        Sample:
        
        ```python
        import requests
        from requests_auth import OAuth2AuthorizationCode
        
        requests.get('http://www.example.com', auth=OAuth2AuthorizationCode('https://www.authorization.url', 'https://www.token.url'))
        ```
        
        or
        
        ```python
        import requests
        from requests_auth import oauth2, OAuth2Flow
        
        requests.get('http://www.example.com', auth=oauth2(OAuth2Flow.AuthorizationCode, 'https://www.authorization.url', 'https://www.token.url'))
        ```
        
        #### Parameters ####
        
        | Name                    | Description                | Mandatory | Default value |
        |:------------------------|:---------------------------|:----------|:--------------|
        | `authorization_url`     | OAuth 2 authorization URL. | Mandatory |               |
        | `token_url`             | OAuth 2 token URL.         | Mandatory |               |
        | `redirect_uri_endpoint` | Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>. | Optional | ''             |
        | `redirect_uri_port`     | The port on which the server listening for the OAuth 2 code will be started. | Optional | 5000 |
        | `timeout`               | Maximum amount of seconds to wait for a code or a token to be received once requested. | Optional | 60 |
        | `success_display_time`  | In case a code is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser. | Optional | 1 |
        | `failure_display_time`  | In case received code is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser. | Optional | 5000 |
        | `header_name`           | Name of the header field used to send token. | Optional | Authorization |
        | `header_value`          | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        | `response_type`         | Value of the response_type query parameter if not already provided in authorization URL. | Optional | code |
        | `token_field_name`      | Field name containing the token. | Optional | access_token |
        | `code_field_name`       | Field name containing the code. | Optional | code |
        | `username`              | User name in case basic authentication should be used to retrieve token. | Optional |  |
        | `password`              | User password in case basic authentication should be used to retrieve token. | Optional |  |
        
        Any other parameter will be put as query parameter in the authorization URL and as body parameters in the token URL.        
        
        Usual parameters are:
                
        | Name            | Description                                                          |
        |:----------------|:---------------------------------------------------------------------|
        | `client_id`     | Corresponding to your Application ID (in Microsoft Azure app portal) |
        | `client_secret` | If client is not authenticated with the authorization server         |
        | `nonce`         | Refer to [OpenID ID Token specifications][3] for more details        |
        
        ### Resource Owner Password Credentials flow ###
        
        Sample:
        
        ```python
        import requests
        from requests_auth import OAuth2ResourceOwnerPasswordCredentials
        
        requests.get('http://www.example.com', auth=OAuth2ResourceOwnerPasswordCredentials('https://www.token.url', 'user name', 'user password'))
        ```
        
        or
        
        ```python
        import requests
        from requests_auth import oauth2, OAuth2Flow
        
        requests.get('http://www.example.com', auth=oauth2(OAuth2Flow.PasswordCredentials, 'https://www.token.url', 'user name', 'user password'))
        ```
        
        #### Parameters ####
        
        | Name               | Description                                  | Mandatory | Default value |
        |:-------------------|:---------------------------------------------|:----------|:--------------|
        | `token_url`        | OAuth 2 token URL.                           | Mandatory |               |
        | `username`         | Resource owner user name.                    | Mandatory |               |
        | `password`         | Resource owner password.                     | Mandatory |               |
        | `timeout`          | Maximum amount of seconds to wait for a token to be received once requested. | Optional | 60            |
        | `header_name`      | Name of the header field used to send token. | Optional  | Authorization |
        | `header_value`     | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        | `scope`            | Scope parameter sent to token URL as body. Can also be a list of scopes. | Optional |  |
        | `token_field_name` | Field name containing the token.             | Optional  | access_token  |
        
        Any other parameter will be put as body parameter in the token URL.
        
        ### Client Credentials flow ###
        
        Sample:
        
        ```python
        import requests
        from requests_auth import OAuth2ClientCredentials
        
        requests.get('http://www.example.com', auth=OAuth2ClientCredentials('https://www.token.url', 'user name', 'user password'))
        ```
        
        or
        
        ```python
        import requests
        from requests_auth import oauth2, OAuth2Flow
        
        requests.get('http://www.example.com', auth=oauth2(OAuth2Flow.ClientCredentials, 'https://www.token.url', 'user name', 'user password'))
        ```
        
        #### Parameters ####
        
        | Name               | Description                                  | Mandatory | Default value |
        |:-------------------|:---------------------------------------------|:----------|:--------------|
        | `token_url`        | OAuth 2 token URL.                           | Mandatory |               |
        | `username`         | Resource owner user name.                    | Mandatory |               |
        | `password`         | Resource owner password.                     | Mandatory |               |
        | `timeout`          | Maximum amount of seconds to wait for a token to be received once requested. | Optional | 60            |
        | `header_name`      | Name of the header field used to send token. | Optional  | Authorization |
        | `header_value`     | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        | `scope`            | Scope parameter sent to token URL as body. Can also be a list of scopes. | Optional |  |
        | `token_field_name` | Field name containing the token.             | Optional  | access_token  |
        
        Any other parameter will be put as body parameter in the token URL.
        
        ### Implicit flow ###
        
        Sample:
        
        ```python
        import requests
        from requests_auth import OAuth2Implicit
        
        requests.get('http://www.example.com', auth=OAuth2Implicit('https://www.authorization.url'))
        ```
        
        or
        
        ```python
        import requests
        from requests_auth import oauth2, OAuth2Flow
        
        requests.get('http://www.example.com', auth=oauth2(OAuth2Flow.Implicit, 'https://www.authorization.url'))
        ```
        
        #### Parameters ####
        
        | Name                    | Description                | Mandatory | Default value |
        |:------------------------|:---------------------------|:----------|:--------------|
        | `authorization_url`     | OAuth 2 authorization URL. | Mandatory |               |
        | `response_type`         | Value of the response_type query parameter if not already provided in authorization URL. | Optional | token |
        | `token_field_name`      | Field name containing the token. | Optional | id_token if response_type is id_token, otherwise access_token |
        | `redirect_uri_endpoint` | Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>. | Optional | ''             |
        | `redirect_uri_port`     | The port on which the server listening for the OAuth 2 token will be started. | Optional | 5000 |
        | `timeout`               | Maximum amount of seconds to wait for a token to be received once requested. | Optional | 60 |
        | `success_display_time`  | In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser. | Optional | 1 |
        | `failure_display_time`  | In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser. | Optional | 5000 |
        | `header_name`           | Name of the header field used to send token. | Optional | Authorization |
        | `header_value`          | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        
        Any other parameter will be put as query parameter in the authorization URL.        
        
        Usual parameters are:
        
        | Name            | Description                                                          |
        |:----------------|:---------------------------------------------------------------------|
        | `client_id`     | Corresponding to your Application ID (in Microsoft Azure app portal) |
        | `nonce`         | Refer to [OpenID ID Token specifications][3] for more details        |
        | `prompt`        | none to avoid prompting the user if a session is already opened.     |
        
        #### Common providers ####
        
        ##### Microsoft - Azure Active Directory (OAuth2 Access Token) #####
        
        Sample:
        
        ```python
        import requests
        from requests_auth import AzureActiveDirectoryImplicit
        
        
        aad = AzureActiveDirectoryImplicit(tenant_id='45239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
        requests.get('http://www.example.com', auth=aad)
        ```
        
        or
        
        ```python
        import requests
        from requests_auth import aad, OAuth2Flow
        
        requests.get('http://www.example.com', auth=aad(OAuth2Flow.Implicit, tenant_id='45239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd'))
        ```
        
        ###### Parameters ######
        
        | Name                    | Description                | Mandatory | Default value |
        |:------------------------|:---------------------------|:----------|:--------------|
        | `tenant_id`             | Microsoft Tenant Identifier (formatted as an Universal Unique Identifier). | Mandatory |               |
        | `client_id`             | Microsoft Application Identifier (formatted as an Universal Unique Identifier). | Mandatory |               |
        | `response_type`         | Value of the response_type query parameter if not already provided in authorization URL. | Optional | token |
        | `token_field_name`      | Field name containing the token. | Optional | access_token |
        | `nonce`                 | Refer to [OpenID ID Token specifications][3] for more details | Optional | Newly generated Universal Unique Identifier. |
        | `redirect_uri_endpoint` | Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>. | Optional | ''             |
        | `redirect_uri_port`     | The port on which the server listening for the OAuth 2 token will be started. | Optional | 5000 |
        | `timeout`               | Maximum amount of seconds to wait for a token to be received once requested. | Optional | 60 |
        | `success_display_time`  | In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser. | Optional | 1 |
        | `failure_display_time`  | In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser. | Optional | 5000 |
        | `header_name`           | Name of the header field used to send token. | Optional | Authorization |
        | `header_value`          | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        
        Any other parameter will be put as query parameter in the authorization URL.        
        
        Usual parameters are:
        
        | Name            | Description                                                          |
        |:----------------|:---------------------------------------------------------------------|
        | `prompt`        | none to avoid prompting the user if a session is already opened.     |
        
        ##### Microsoft - Azure Active Directory (OpenID Connect ID token) #####
        
        Sample:
        
        ```python
        import requests
        from requests_auth import AzureActiveDirectoryImplicitIdToken
        
        
        aad = AzureActiveDirectoryImplicitIdToken(tenant_id='45239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
        requests.get('http://www.example.com', auth=aad)
        ```
        
        ###### Parameters ######
        
        | Name                    | Description                | Mandatory | Default value |
        |:------------------------|:---------------------------|:----------|:--------------|
        | `tenant_id`             | Microsoft Tenant Identifier (formatted as an Universal Unique Identifier). | Mandatory |               |
        | `client_id`             | Microsoft Application Identifier (formatted as an Universal Unique Identifier). | Mandatory |               |
        | `response_type`         | Value of the response_type query parameter if not already provided in authorization URL. | Optional | id_token |
        | `token_field_name`      | Field name containing the token. | Optional | id_token |
        | `nonce`                 | Refer to [OpenID ID Token specifications][3] for more details | Optional | Newly generated Universal Unique Identifier. |
        | `redirect_uri_endpoint` | Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>. | Optional | ''             |
        | `redirect_uri_port`     | The port on which the server listening for the OAuth 2 token will be started. | Optional | 5000 |
        | `timeout`               | Maximum amount of seconds to wait for a token to be received once requested. | Optional | 60 |
        | `success_display_time`  | In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser. | Optional | 1 |
        | `failure_display_time`  | In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser. | Optional | 5000 |
        | `header_name`           | Name of the header field used to send token. | Optional | Authorization |
        | `header_value`          | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        
        Any other parameter will be put as query parameter in the authorization URL.        
        
        Usual parameters are:
        
        | Name            | Description                                                          |
        |:----------------|:---------------------------------------------------------------------|
        | `prompt`        | none to avoid prompting the user if a session is already opened.     |
        
        ##### OKTA (OAuth2 Access Token) #####
        
        Sample:
        
        ```python
        import requests
        from requests_auth import OktaImplicit
        
        
        okta = OktaImplicit(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
        requests.get('http://www.example.com', auth=okta)
        ```
        
        or
        
        ```python
        import requests
        from requests_auth import okta, OAuth2Flow
        
        requests.get('http://www.example.com', auth=okta(OAuth2Flow.Implicit, instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd'))
        ```
        
        ###### Parameters ######
        
        | Name                    | Description                | Mandatory | Default value |
        |:------------------------|:---------------------------|:----------|:--------------|
        | `instance`              | OKTA instance (like "testserver.okta-emea.com"). | Mandatory |               |
        | `client_id`             | Microsoft Application Identifier (formatted as an Universal Unique Identifier). | Mandatory |               |
        | `response_type`         | Value of the response_type query parameter if not already provided in authorization URL. | Optional | token |
        | `token_field_name`      | Field name containing the token. | Optional | access_token |
        | `nonce`                 | Refer to [OpenID ID Token specifications][3] for more details. | Optional | Newly generated Universal Unique Identifier. |
        | `scope`                 | Scope parameter sent in query. Can also be a list of scopes. | Optional | ['openid', 'profile', 'email'] |
        | `authorization_server`  | OKTA authorization server. | Optional | '' |
        | `redirect_uri_endpoint` | Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>. | Optional | ''             |
        | `redirect_uri_port`     | The port on which the server listening for the OAuth 2 token will be started. | Optional | 5000 |
        | `timeout`               | Maximum amount of seconds to wait for a token to be received once requested. | Optional | 60 |
        | `success_display_time`  | In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser. | Optional | 1 |
        | `failure_display_time`  | In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser. | Optional | 5000 |
        | `header_name`           | Name of the header field used to send token. | Optional | Authorization |
        | `header_value`          | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        
        Any other parameter will be put as query parameter in the authorization URL.        
        
        Usual parameters are:
        
        | Name            | Description                                                          |
        |:----------------|:---------------------------------------------------------------------|
        | `prompt`        | none to avoid prompting the user if a session is already opened.     |
        
        ##### OKTA (OpenID Connect ID token) #####
        
        Sample:
        
        ```python
        import requests
        from requests_auth import OktaImplicitIdToken
        
        
        okta = OktaImplicitIdToken(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
        requests.get('http://www.example.com', auth=okta)
        ```
        
        ###### Parameters ######
        
        | Name                    | Description                | Mandatory | Default value |
        |:------------------------|:---------------------------|:----------|:--------------|
        | `instance`              | OKTA instance (like "testserver.okta-emea.com"). | Mandatory |               |
        | `client_id`             | Microsoft Application Identifier (formatted as an Universal Unique Identifier). | Mandatory |               |
        | `response_type`         | Value of the response_type query parameter if not already provided in authorization URL. | Optional | id_token |
        | `token_field_name`      | Field name containing the token. | Optional | id_token |
        | `nonce`                 | Refer to [OpenID ID Token specifications][3] for more details. | Optional | Newly generated Universal Unique Identifier. |
        | `scope`                 | Scope parameter sent in query. Can also be a list of scopes. | Optional | ['openid', 'profile', 'email'] |
        | `authorization_server`  | OKTA authorization server. | Optional | '' |
        | `redirect_uri_endpoint` | Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>. | Optional | ''             |
        | `redirect_uri_port`     | The port on which the server listening for the OAuth 2 token will be started. | Optional | 5000 |
        | `timeout`               | Maximum amount of seconds to wait for a token to be received once requested. | Optional | 60 |
        | `success_display_time`  | In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser. | Optional | 1 |
        | `failure_display_time`  | In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser. | Optional | 5000 |
        | `header_name`           | Name of the header field used to send token. | Optional | Authorization |
        | `header_value`          | Format used to send the token value. "{token}" must be present as it will be replaced by the actual token. | Optional | Bearer {token} |
        
        Any other parameter will be put as query parameter in the authorization URL.        
        
        Usual parameters are:
        
        | Name            | Description                                                          |
        |:----------------|:---------------------------------------------------------------------|
        | `prompt`        | none to avoid prompting the user if a session is already opened.     |
        
        ### Managing token cache ###
        
        To avoid asking for a new token every new request, a token cache is used.
        
        Default cache is in memory but it is also possible to use a physical cache using the following method:
        
        ```python
        from requests_auth import OAuth2, JsonTokenFileCache
        
        OAuth2.token_cache = JsonTokenFileCache('my_token_cache')
        ```
        
        
        ## API key in header ##
        
        Sample:
        
        ```python
        import requests
        from requests_auth import HeaderApiKey
        
        requests.get('http://www.example.com', auth=HeaderApiKey('my_api_key'))
        ```
        
        ### Parameters ###
        
        | Name                    | Description                    | Mandatory | Default value |
        |:------------------------|:-------------------------------|:----------|:--------------|
        | `api_key`               | The API key that will be sent. | Mandatory |               |
        | `header_name`           | Name of the header field.      | Optional  | "X-API-Key"   |
        
        ## API key in query ##
        
        Sample:
        
        ```python
        import requests
        from requests_auth import QueryApiKey
        
        requests.get('http://www.example.com', auth=QueryApiKey('my_api_key'))
        ```
        
        ### Parameters ###
        
        | Name                    | Description                    | Mandatory | Default value |
        |:------------------------|:-------------------------------|:----------|:--------------|
        | `api_key`               | The API key that will be sent. | Mandatory |               |
        | `query_parameter_name`  | Name of the query parameter.   | Optional  | "api_key"     |
        
        ## Basic ##
        
        Sample:
        
        ```python
        import requests
        from requests_auth import Basic
        
        requests.get('http://www.example.com', auth=Basic('username', 'password'))
        ```
        
        ### Parameters ###
        
        | Name                    | Description                    | Mandatory | Default value |
        |:------------------------|:-------------------------------|:----------|:--------------|
        | `username`              | User name.                     | Mandatory |               |
        | `password`              | User password.                 | Mandatory |               |
        
        ## NTLM ##
        
        Requires [requests-negotiate-sspi module][4] or [requests_ntlm module][5] depending on provided parameters.
        
        Sample:
        
        ```python
        import requests
        from requests_auth import NTLM
        
        requests.get('http://www.example.com', auth=NTLM())
        ```
        
        ### Parameters ###
        
        | Name                    | Description                    | Mandatory | Default value |
        |:------------------------|:-------------------------------|:----------|:--------------|
        | `username`              | User name.                     | Mandatory if requests_negotiate_sspi module is not installed. In such a case requests_ntlm module is mandatory. |               |
        | `password`              | User password.                 | Mandatory if requests_negotiate_sspi module is not installed. In such a case requests_ntlm module is mandatory. |               |
        
        ## Multiple authentication at once ##
        
        You can also use a combination of authentication as in the following sample:
        
        ```python
        import requests
        from requests_auth import Auths, HeaderApiKey, OAuth2Implicit
        
        api_key = HeaderApiKey('my_api_key')
        oauth2 = OAuth2Implicit('https://www.example.com')
        requests.get('http://www.example.com', auth=Auths(api_key, oauth2))
        ```
        
        [1]: https://pypi.python.org/pypi/requests "requests module"
        [2]: http://docs.python-requests.org/en/master/user/authentication/ "authentication parameter on requests module"
        [3]: http://openid.net/specs/openid-connect-core-1_0.html#IDToken "OpenID ID Token specifications"
        [4]: https://pypi.python.org/pypi/requests-negotiate-sspi "requests-negotiate-sspi module"
        [5]: https://pypi.python.org/pypi/requests_ntlm "requests_ntlm module"
        
Keywords: authentication,ntlm,oauth2,azure-active-directory,azure-ad,okta,apikey,multiple
Platform: Windows
Platform: Linux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Build Tools
Description-Content-Type: text/markdown
