Provides authentication classes to be used with requests authentication parameter.
Some of the supported authentication
Most of OAuth2 flows are supported.
If the one you are looking for is not yet supported, feel free to ask for its implementation.
Authorization Code Grant is implemented following rfc6749.
Use requests_auth.OAuth2AuthorizationCode to configure this kind of authentication.
import requests
from requests_auth import OAuth2AuthorizationCode
requests.get('https://www.example.com', auth=OAuth2AuthorizationCode('https://www.authorization.url', 'https://www.token.url'))
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
authorization_url | OAuth 2 authorization URL. | Mandatory | |
token_url | OAuth 2 token URL. | Mandatory | |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
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 | |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as query parameter in the authorization URL and as body parameters in the token URL.
Usual extra 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 for more details |
Most of OAuth2 Authorization Code Grant providers are supported.
If the one you are looking for is not yet supported, feel free to ask for its implementation.
Okta Authorization Code Grant providing access tokens is supported.
Use requests_auth.OktaAuthorizationCode to configure this kind of authentication.
import requests
from requests_auth import OktaAuthorizationCode
okta = OktaAuthorizationCode(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
requests.get('https://www.example.com', auth=okta)
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
instance | Okta instance (like "testserver.okta-emea.com"). | Mandatory | |
client_id | Okta 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
nonce | Refer to OpenID ID Token specifications for more details. | Optional | Newly generated Universal Unique Identifier. |
scope | Scope parameter sent in query. Can also be a list of scopes. | Optional | openid |
authorization_server | Okta authorization server. | Optional | 'default' |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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} |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as query parameter in the authorization URL.
Usual extra parameters are:
| Name | Description |
|---|---|
prompt | none to avoid prompting the user if a session is already opened. |
WakaTime Authorization Code Grant providing access tokens is supported.
Use requests_auth.WakaTimeAuthorizationCode to configure this kind of authentication.
import requests
from requests_auth import WakaTimeAuthorizationCode
waka_time = WakaTimeAuthorizationCode(client_id="aPJQV0op6Pu3b66MWDi9b1wB", client_secret="waka_sec_0c5MB", scope="email")
requests.get('https://wakatime.com/api/v1/users/current', auth=waka_time)
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
client_id | WakaTime Application Identifier (formatted as an Universal Unique Identifier). | Mandatory | |
client_secret | WakaTime Application Secret (formatted as waka_sec_ followed by an Universal Unique Identifier). | Mandatory | |
scope | Scope parameter sent in query. Can also be a list of scopes. | 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
nonce | Refer to OpenID ID Token specifications for more details. | Optional | Newly generated Universal Unique Identifier. |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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} |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as query parameter in the authorization URL.
Proof Key for Code Exchange is implemented following rfc7636.
Use requests_auth.OAuth2AuthorizationCodePKCE to configure this kind of authentication.
import requests
from requests_auth import OAuth2AuthorizationCodePKCE
requests.get('https://www.example.com', auth=OAuth2AuthorizationCodePKCE('https://www.authorization.url', 'https://www.token.url'))
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
authorization_url | OAuth 2 authorization URL. | Mandatory | |
token_url | OAuth 2 token URL. | Mandatory | |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
code_field_name | Field name containing the code. | Optional | code |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as query parameter in the authorization URL and as body parameters in the token URL.
Usual extra 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 for more details |
Most of OAuth2 Proof Key for Code Exchange providers are supported.
If the one you are looking for is not yet supported, feel free to ask for its implementation.
Okta Proof Key for Code Exchange providing access tokens is supported.
Use requests_auth.OktaAuthorizationCodePKCE to configure this kind of authentication.
import requests
from requests_auth import OktaAuthorizationCodePKCE
okta = OktaAuthorizationCodePKCE(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
requests.get('https://www.example.com', auth=okta)
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
instance | Okta instance (like "testserver.okta-emea.com"). | Mandatory | |
client_id | Okta 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 | code |
token_field_name | Field name containing the token. | Optional | access_token |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
code_field_name | Field name containing the code. | Optional | code |
nonce | Refer to OpenID ID Token specifications for more details. | Optional | Newly generated Universal Unique Identifier. |
scope | Scope parameter sent in query. Can also be a list of scopes. | Optional | openid |
authorization_server | Okta authorization server. | Optional | 'default' |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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} |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as query parameter in the authorization URL and as body parameters in the token URL.
Usual extra parameters are:
| Name | Description |
|---|---|
client_secret | If client is not authenticated with the authorization server |
nonce | Refer to OpenID ID Token specifications for more details |
Resource Owner Password Credentials Grant is implemented following rfc6749.
Use requests_auth.OAuth2ResourceOwnerPasswordCredentials to configure this kind of authentication.
import requests
from requests_auth import OAuth2ResourceOwnerPasswordCredentials
requests.get('https://www.example.com', auth=OAuth2ResourceOwnerPasswordCredentials('https://www.token.url', 'user name', 'user password'))
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
token_url | OAuth 2 token URL. | Mandatory | |
username | Resource owner user name. | Mandatory | |
password | Resource owner password. | Mandatory | |
session_auth | Client authentication if the client type is confidential or the client was issued client credentials (or assigned other authentication requirements). Can be a tuple or any requests authentication class instance. | Optional | |
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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as body parameter in the token URL.
Most of OAuth2 Resource Owner Password Credentials providers are supported.
If the one you are looking for is not yet supported, feel free to ask for its implementation.
Okta Resource Owner Password Credentials providing access tokens is supported.
Use requests_auth.OktaResourceOwnerPasswordCredentials to configure this kind of authentication.
import requests
from requests_auth import OktaResourceOwnerPasswordCredentials
okta = OktaResourceOwnerPasswordCredentials(instance='testserver.okta-emea.com', username='user name', password='user password', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_secret="0c5MB")
requests.get('https://www.example.com', auth=okta)
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
instance | Okta instance (like "testserver.okta-emea.com"). | Mandatory | |
username | Resource owner user name. | Mandatory | |
password | Resource owner password. | Mandatory | |
client_id | Okta Application Identifier (formatted as an Universal Unique Identifier). | Mandatory | |
client_secret | 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 in query. Can also be a list of scopes. | Optional | openid |
token_field_name | Field name containing the token. | Optional | access_token |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as body parameters in the token URL.
Client Credentials Grant is implemented following rfc6749.
Use requests_auth.OAuth2ClientCredentials to configure this kind of authentication.
import requests
from requests_auth import OAuth2ClientCredentials
requests.get('https://www.example.com', auth=OAuth2ClientCredentials('https://www.token.url', client_id='id', client_secret='secret'))
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
token_url | OAuth 2 token URL. | Mandatory | |
client_id | Resource owner user name. | Mandatory | |
client_secret | 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as body parameter in the token URL.
Most of OAuth2 Client Credentials Grant providers are supported.
If the one you are looking for is not yet supported, feel free to ask for its implementation.
Okta Client Credentials Grant providing access tokens is supported.
Use requests_auth.OktaClientCredentials to configure this kind of authentication.
import requests
from requests_auth import OktaClientCredentials
okta = OktaClientCredentials(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_secret="secret", scope=["scope1", "scope2"])
requests.get('https://www.example.com', auth=okta)
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
instance | Okta instance (like "testserver.okta-emea.com"). | Mandatory | |
client_id | Okta Application Identifier (formatted as an Universal Unique Identifier). | Mandatory | |
client_secret | Resource owner password. | Mandatory | |
scope | Scope parameter sent in query. Can also be a list of scopes. | Mandatory | |
authorization_server | Okta authorization server. | Optional | 'default' |
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} |
token_field_name | Field name containing the token. | Optional | access_token |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
session | requests.Session instance that will be used to request the token. Use it to provide a custom proxying rule for instance. | Optional |
Any other parameter will be put as query parameter in the token URL.
Implicit Grant is implemented following rfc6749.
Use requests_auth.OAuth2Implicit to configure this kind of authentication.
import requests
from requests_auth import OAuth2Implicit
requests.get('https://www.example.com', auth=OAuth2Implicit('https://www.authorization.url'))
Note:
| 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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 extra parameters are:
| Name | Description |
|---|---|
client_id | Corresponding to your Application ID (in Microsoft Azure app portal) |
nonce | Refer to OpenID ID Token specifications for more details |
prompt | none to avoid prompting the user if a session is already opened. |
Most of OAuth2 Implicit Grant providers are supported.
If the one you are looking for is not yet supported, feel free to ask for its implementation.
Microsoft identity platform access tokens are supported.
Use requests_auth.AzureActiveDirectoryImplicit to configure this kind of authentication.
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('https://www.example.com', auth=aad)
Note:
You can retrieve Microsoft Azure Active Directory application information thanks to the application list on Azure portal.
| 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
nonce | Refer to OpenID ID Token specifications for more details | Optional | Newly generated Universal Unique Identifier. |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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 extra parameters are:
| Name | Description |
|---|---|
prompt | none to avoid prompting the user if a session is already opened. |
Microsoft identity platform ID tokens are supported.
Use requests_auth.AzureActiveDirectoryImplicitIdToken to configure this kind of authentication.
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('https://www.example.com', auth=aad)
Note:
You can retrieve Microsoft Azure Active Directory application information thanks to the application list on Azure portal.
| 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
nonce | Refer to OpenID ID Token specifications for more details | Optional | Newly generated Universal Unique Identifier. |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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 extra parameters are:
| Name | Description |
|---|---|
prompt | none to avoid prompting the user if a session is already opened. |
Okta Implicit Grant providing access tokens is supported.
Use requests_auth.OktaImplicit to configure this kind of authentication.
import requests
from requests_auth import OktaImplicit
okta = OktaImplicit(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
requests.get('https://www.example.com', auth=okta)
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
instance | Okta instance (like "testserver.okta-emea.com"). | Mandatory | |
client_id | Okta 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
nonce | Refer to OpenID ID Token specifications 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 | 'default' |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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 extra parameters are:
| Name | Description |
|---|---|
prompt | none to avoid prompting the user if a session is already opened. |
Okta Implicit Grant providing ID tokens is supported.
Use requests_auth.OktaImplicitIdToken to configure this kind of authentication.
import requests
from requests_auth import OktaImplicitIdToken
okta = OktaImplicitIdToken(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
requests.get('https://www.example.com', auth=okta)
Note:
| Name | Description | Mandatory | Default value |
|---|---|---|---|
instance | Okta instance (like "testserver.okta-emea.com"). | Mandatory | |
client_id | Okta 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 |
early_expiry | Number of seconds before actual token expiry where token will be considered as expired. Used to ensure token will not expire between the time of retrieval and the time the request reaches the actual server. Set it to 0 to deactivate this feature and use the same token until actual expiry. | Optional | 30.0 |
nonce | Refer to OpenID ID Token specifications 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 | 'default' |
redirect_uri_domain | FQDN to use in the redirect_uri when localhost is not allowed. | Optional | localhost |
redirect_uri_endpoint | Custom endpoint that will be used as redirect_uri the following way: http://<redirect_uri_domain>:<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 |
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 extra parameters are:
| Name | Description |
|---|---|
prompt | none to avoid prompting the user if a session is already opened. |
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.
You need to provide the location of your token cache file. It can be a full or relative path (str or `pathlib.Path).
If the file already exists it will be used, if the file do not exist it will be created.
from requests_auth import OAuth2, JsonTokenFileCache
OAuth2.token_cache = JsonTokenFileCache('path/to/my_token_cache.json')
You can configure the browser display settings thanks to requests_auth.OAuth2.display as in the following:
from requests_auth import OAuth2, DisplaySettings
OAuth2.display = DisplaySettings()
The following parameters can be provided to DisplaySettings:
| Name | Description | Default value |
|---|---|---|
success_display_time | In case a code or token is successfully received, this is the maximum amount of milliseconds the success page will be displayed in your browser. | 1 |
success_html | In case a code or token is successfully received, this is the success page that will be displayed in your browser. {display_time} is expected in this content. | |
failure_display_time | In case received code or token is not valid, this is the maximum amount of milliseconds the failure page will be displayed in your browser. | 10_000 |
failure_html | In case received code or token is not valid, this is the failure page that will be displayed in your browser. {information} and {display_time} are expected in this content. |
You can send an API key inside the header of your request using requests_auth.HeaderApiKey.
import requests
from requests_auth import HeaderApiKey
requests.get('https://www.example.com', auth=HeaderApiKey('my_api_key'))
| 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" |
You can send an API key inside the query parameters of your request using requests_auth.QueryApiKey.
import requests
from requests_auth import QueryApiKey
requests.get('https://www.example.com', auth=QueryApiKey('my_api_key'))
| 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" |
You can use basic authentication using requests_auth.Basic.
The only advantage of using this class instead of requests native support of basic authentication, is to be able to use it in multiple authentication.
import requests
from requests_auth import Basic
requests.get('https://www.example.com', auth=Basic('username', 'password'))
| Name | Description | Mandatory | Default value |
|---|---|---|---|
username | User name. | Mandatory | |
password | User password. | Mandatory |
Requires requests-negotiate-sspi module or requests_ntlm module depending on provided parameters.
You can use Windows authentication using requests_auth.NTLM.
import requests
from requests_auth import NTLM
requests.get('https://www.example.com', auth=NTLM())
| 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. |
You can also use a combination of authentication using + or & as in the following sample:
import requests
from requests_auth import HeaderApiKey, OAuth2Implicit
api_key = HeaderApiKey('my_api_key')
oauth2 = OAuth2Implicit('https://www.example.com')
requests.get('https://www.example.com', auth=api_key + oauth2)
This is supported on every authentication class exposed by requests_auth, but you can also enable it on your own authentication classes by using requests_auth.SupportMultiAuth as in the following sample:
from requests_auth import SupportMultiAuth
# TODO Import your own auth here
from my_package import MyAuth
class MyMultiAuth(MyAuth, SupportMultiAuth):
pass
Testing the code using requests_auth authentication classes can be achieved using provided pytest fixtures.
from requests_auth.testing import token_cache_mock, token_mock
def test_something(token_cache_mock):
# perform code using authentication
pass
Use this fixture to mock authentication success for any of the following classes:
By default, an access token with value 2YotnFZFEjr1zCsicMWpAA is generated.
You can however return your custom token by providing your own token_mock fixture as in the following sample:
import pytest
from requests_auth.testing import token_cache_mock
@pytest.fixture
def token_mock() -> str:
return "MyCustomTokenValue"
def test_something(token_cache_mock):
# perform code using authentication
pass
You can even return a more complex token by using the create_token function.
Note that pyjwt is a required dependency in this case as it is used to generate the token returned by the authentication.
import pytest
from requests_auth.testing import token_cache_mock, create_token
@pytest.fixture
def token_mock() -> str:
expiry = None # TODO Compute your expiry
return create_token(expiry)
def test_something(token_cache_mock):
# perform code using authentication
pass
This pytest fixture will return the token cache and ensure it is reset at the end of the test case.
from requests_auth.testing import token_cache
def test_something(token_cache):
# perform code using authentication
pass
This pytest fixture will allow to mock the behavior of a web browser.
With this pytest fixture you will be allowed to fine tune your authentication related failures handling.
pyjwt is a required dependency if you use create_token helper function.
import datetime
from requests_auth.testing import browser_mock, BrowserMock, create_token
def test_something(browser_mock: BrowserMock):
token_expiry = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1)
token = create_token(token_expiry)
tab = browser_mock.add_response(
opened_url="http://url_opened_by_browser?state=1234",
reply_url=f"http://localhost:5000#access_token={token}&state=1234",
)
# perform code using authentication
tab.assert_success()
I love requests_auth. As a ~15 year pythonista, this library makes working with OAuth services a breeze. <333
Randall Degges, Head of Evangelism, Okta
FAQs
Authentication for Requests
We found that requests-auth demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious Go packages are impersonating popular libraries to install hidden loader malware on Linux and macOS, targeting developers with obfuscated payloads.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.