requests-auth

Easy Authentication for Requests

These details have not been verified by PyPI

Project links

Project 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 ####

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>authorization_url</td>
<td>OAuth 2 authorization URL.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>token_url</td>
<td>OAuth 2 token URL.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>redirect_uri_endpoint</td>
<td>Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>.</td>
<td>Optional</td>
<td>''</td>
</tr>
<tr>
<td>redirect_uri_port</td>
<td>The port on which the server listening for the OAuth 2 code will be started.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>timeout</td>
<td>Maximum amount of seconds to wait for a code or a token to be received once requested.</td>
<td>Optional</td>
<td>60</td>
</tr>
<tr>
<td>success_display_time</td>
<td>In case a code is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser.</td>
<td>Optional</td>
<td>1</td>
</tr>
<tr>
<td>failure_display_time</td>
<td>In case received code is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>header_name</td>
<td>Name of the header field used to send token.</td>
<td>Optional</td>
<td>Authorization</td>
</tr>
<tr>
<td>header_value</td>
<td>Format used to send the token value. "{token}" must be present as it will be replaced by the actual token.</td>
<td>Optional</td>
<td>Bearer {token}</td>
</tr>
<tr>
<td>token_field_name</td>
<td>Field name containing the token.</td>
<td>Optional</td>
<td>access_token</td>
</tr>
<tr>
<td>username</td>
<td>User name in case basic authentication should be used to retrieve token.</td>
<td>Optional</td>
<td></td>
</tr>
<tr>
<td>password</td>
<td>User password in case basic authentication should be used to retrieve token.</td>
<td>Optional</td>
<td></td>
</tr>
<tr>
<td>any other parameter</td>
<td>all additional authorization parameters that should be put as query parameter in the authorization URL and as body parameters in the token URL.
Common parameters are:

* client_id: Corresponding to your Application ID (in Microsoft Azure app portal)
* client_secret: If client is not authenticated with the authorization server
* response_type: code for Microsoft
* nonce: Refer to [OpenID ID Token specifications][3] for more details</td>
<td>Optional</td>
<td></td>
</tr>
</table>

### 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 ####

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>token_url</td>
<td>OAuth 2 token URL.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>username</td>
<td>Resource owner user name.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>password</td>
<td>Resource owner password.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>timeout</td>
<td>Maximum amount of seconds to wait for a token to be received once requested.</td>
<td>Optional</td>
<td>60</td>
</tr>
<tr>
<td>header_name</td>
<td>Name of the header field used to send token.</td>
<td>Optional</td>
<td>Authorization</td>
</tr>
<tr>
<td>header_value</td>
<td>Format used to send the token value. "{token}" must be present as it will be replaced by the actual token.</td>
<td>Optional</td>
<td>Bearer {token}</td>
</tr>
<tr>
<td>scope</td>
<td>Scope parameter sent to token URL as body. Can also be a list of scopes.</td>
<td>Optional</td>
<td></td>
</tr>
<tr>
<td>token_field_name</td>
<td>Field name containing the token.</td>
<td>Optional</td>
<td>access_token</td>
</tr>
<tr>
<td>any other parameter</td>
<td>all additional authorization parameters that should be put as body parameters in the token URL.</td>
<td>Optional</td>
<td></td>
</tr>
</table>

### 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 ####

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>token_url</td>
<td>OAuth 2 token URL.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>username</td>
<td>Resource owner user name.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>password</td>
<td>Resource owner password.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>timeout</td>
<td>Maximum amount of seconds to wait for a token to be received once requested.</td>
<td>Optional</td>
<td>60</td>
</tr>
<tr>
<td>header_name</td>
<td>Name of the header field used to send token.</td>
<td>Optional</td>
<td>Authorization</td>
</tr>
<tr>
<td>header_value</td>
<td>Format used to send the token value. "{token}" must be present as it will be replaced by the actual token.</td>
<td>Optional</td>
<td>Bearer {token}</td>
</tr>
<tr>
<td>scope</td>
<td>Scope parameter sent to token URL as body. Can also be a list of scopes.</td>
<td>Optional</td>
<td></td>
</tr>
<tr>
<td>token_field_name</td>
<td>Field name containing the token.</td>
<td>Optional</td>
<td>access_token</td>
</tr>
<tr>
<td>any other parameter</td>
<td>all additional authorization parameters that should be put as body parameters in the token URL.</td>
<td>Optional</td>
<td></td>
</tr>
</table>

### 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 ####

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>authorization_url</td>
<td>OAuth 2 authorization URL.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>redirect_uri_endpoint</td>
<td>Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>.</td>
<td>Optional</td>
<td>''</td>
</tr>
<tr>
<td>redirect_uri_port</td>
<td>The port on which the server listening for the OAuth 2 token will be started.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>timeout</td>
<td>Maximum amount of seconds to wait for a token to be received once requested.</td>
<td>Optional</td>
<td>60</td>
</tr>
<tr>
<td>success_display_time</td>
<td>In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser.</td>
<td>Optional</td>
<td>1</td>
</tr>
<tr>
<td>failure_display_time</td>
<td>In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>header_name</td>
<td>Name of the header field used to send token.</td>
<td>Optional</td>
<td>Authorization</td>
</tr>
<tr>
<td>header_value</td>
<td>Format used to send the token value. "{token}" must be present as it will be replaced by the actual token.</td>
<td>Optional</td>
<td>Bearer {token}</td>
</tr>
<tr>
<td>any other parameter</td>
<td>all additional authorization parameters that should be put as query parameter in the authorization URL.
Common parameters are:

* client_id: Corresponding to your Application ID (in Microsoft Azure app portal)
* response_type: id_token for Microsoft
* nonce: Refer to [OpenID ID Token specifications][3] for more details</td>
<td>Optional</td>
<td></td>
</tr>
</table>

#### Common providers ####

##### Microsoft - Azure Active Directory #####

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 ######

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>tenant_id</td>
<td>Microsoft Tenant Identifier (formatted as an Universal Unique Identifier).</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>client_id</td>
<td>Microsoft Application Identifier (formatted as an Universal Unique Identifier).</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>nonce</td>
<td>Refer to http://openid.net/specs/openid-connect-core-1_0.html#IDToken for more details.</td>
<td>Optional</td>
<td>Newly generated Universal Unique Identifier.</td>
</tr>
<tr>
<td>redirect_uri_endpoint</td>
<td>Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>.</td>
<td>Optional</td>
<td>''</td>
</tr>
<tr>
<td>redirect_uri_port</td>
<td>The port on which the server listening for the OAuth 2 token will be started.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>timeout</td>
<td>Maximum amount of seconds to wait for a token to be received once requested.</td>
<td>Optional</td>
<td>60</td>
</tr>
<tr>
<td>success_display_time</td>
<td>In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser.</td>
<td>Optional</td>
<td>1</td>
</tr>
<tr>
<td>failure_display_time</td>
<td>In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>header_name</td>
<td>Name of the header field used to send token.</td>
<td>Optional</td>
<td>Authorization</td>
</tr>
<tr>
<td>header_value</td>
<td>Format used to send the token value. "{token}" must be present as it will be replaced by the actual token.</td>
<td>Optional</td>
<td>Bearer {token}</td>
</tr>
<tr>
<td>any other parameter</td>
<td>all additional authorization parameters that should be put as query parameter in the authorization URL.</td>
<td>Optional</td>
<td></td>
</tr>
</table>

##### OKTA (implicit flow) #####

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 ######

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>instance</td>
<td>OKTA instance (like "testserver.okta-emea.com").</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>client_id</td>
<td>Microsoft Application Identifier (formatted as an Universal Unique Identifier).</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>nonce</td>
<td>Refer to http://openid.net/specs/openid-connect-core-1_0.html#IDToken for more details.</td>
<td>Optional</td>
<td>Newly generated Universal Unique Identifier.</td>
</tr>
<tr>
<td>scope</td>
<td>Scope parameter sent in query. Can also be a list of scopes.</td>
<td>Optional</td>
<td>['openid', 'profile', 'email']</td>
</tr>
<tr>
<td>authorization_server</td>
<td>OKTA authorization server.</td>
<td>Optional</td>
<td>''</td>
</tr>
<tr>
<td>redirect_uri_endpoint</td>
<td>Custom endpoint that will be used as redirect_uri the following way: http://localhost:<redirect_uri_port>/<redirect_uri_endpoint>.</td>
<td>Optional</td>
<td>''</td>
</tr>
<tr>
<td>redirect_uri_port</td>
<td>The port on which the server listening for the OAuth 2 token will be started.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>timeout</td>
<td>Maximum amount of seconds to wait for a token to be received once requested.</td>
<td>Optional</td>
<td>60</td>
</tr>
<tr>
<td>success_display_time</td>
<td>In case a token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser.</td>
<td>Optional</td>
<td>1</td>
</tr>
<tr>
<td>failure_display_time</td>
<td>In case received token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser.</td>
<td>Optional</td>
<td>5000</td>
</tr>
<tr>
<td>header_name</td>
<td>Name of the header field used to send token.</td>
<td>Optional</td>
<td>Authorization</td>
</tr>
<tr>
<td>header_value</td>
<td>Format used to send the token value. "{token}" must be present as it will be replaced by the actual token.</td>
<td>Optional</td>
<td>Bearer {token}</td>
</tr>
<tr>
<td>any other parameter</td>
<td>all additional authorization parameters that should be put as query parameter in the authorization URL.</td>
<td>Optional</td>
<td></td>
</tr>
</table>

### 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 ###

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>api_key</td>
<td>The API key that will be sent.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>header_name</td>
<td>Name of the header field.</td>
<td>Optional</td>
<td>"X-API-Key"</td>
</tr>
</table>

## 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 ###

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>api_key</td>
<td>The API key that will be sent.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>query_parameter_name</td>
<td>Name of the query parameter.</td>
<td>Optional</td>
<td>"api_key"</td>
</tr>
</table>

## Basic ##

Sample:

```python
import requests
from requests_auth import Basic

requests.get('http://www.example.com', auth=Basic('username', 'password'))
```

### Parameters ###

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>username</td>
<td>User name.</td>
<td>Mandatory</td>
<td></td>
</tr>
<tr>
<td>password</td>
<td>User password.</td>
<td>Mandatory</td>
<td></td>
</tr>
</table>

## 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 ###

<table>
<th>
<td>Description</td>
<td>Mandatory</td>
<td>Default value</td>
</th>
<tr>
<td>username</td>
<td>User name.</td>
<td>Mandatory if requests_negotiate_sspi module is not installed. In such a case requests_ntlm module is mandatory.</td>
<td></td>
</tr>
<tr>
<td>password</td>
<td>User password.</td>
<td>Mandatory if requests_negotiate_sspi module is not installed. In such a case requests_ntlm module is mandatory.</td>
<td></td>
</tr>
</table>

## 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"

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

8.0.0

Jun 18, 2024

7.0.0

Apr 27, 2023

6.0.0

Jan 11, 2022

5.3.0

Jun 6, 2021

5.2.0

Oct 14, 2020

5.1.0

Mar 4, 2020

5.0.2

Dec 12, 2019

5.0.1

Nov 27, 2019

5.0.0

Nov 21, 2019

4.1.0

Nov 13, 2019

4.0.1

Dec 16, 2018

4.0.0

Dec 16, 2018

This version

3.0.0

Nov 13, 2018

2.0.0

Oct 9, 2018

1.0.2

Jan 19, 2018

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

requests_auth-3.0.0.tar.gz (16.4 kB view details)

Uploaded Nov 13, 2018 Source

File details

Details for the file requests_auth-3.0.0.tar.gz.

File metadata

Download URL: requests_auth-3.0.0.tar.gz
Upload date: Nov 13, 2018
Size: 16.4 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/1.8.1 pkginfo/1.4.1 requests/2.19.1 setuptools/39.0.1 requests-toolbelt/0.7.0 clint/0.5.1 CPython/3.6.5 Windows/7

File hashes

Hashes for requests_auth-3.0.0.tar.gz
Algorithm	Hash digest
SHA256	`0b1d67d34d559f9a584bf9d0a896aa63fdfed11323bb438ee8482fe1607d7ad3`
MD5	`665972f3e4054954ab06d4423e93a9bb`
BLAKE2b-256	`b584e6e7d07279e734a182219266f64c99d51c50bee4e60a44a66153522f944d`