Requests - Authentication

Requests - Authentication Mechanisms

The requests library simplifies various authentication schemes used in HTTP. This chapter covers some common types.

• Understanding HTTP Authentication
• Basic Authentication
• Digest Authentication
• OAuth 2.0 Authentication (using requests-oauthlib)

Understanding HTTP Authentication

HTTP authentication involves a client sending credentials (like username and password) to a server to access a protected resource. The server challenges the client for these credentials, typically with a 401 Unauthorized response. The client then resends the request with an Authorization header containing the credentials.

requests provides built-in support for common authentication methods like Basic and Digest, and allows for custom authentication handlers.

Basic Authentication

HTTP Basic Authentication is a simple scheme where the username and password are combined, Base64 encoded, and sent in the Authorization header. While simple, it’s not secure over unencrypted HTTP connections.

requests provides a shortcut for this using the auth parameter, which can take a tuple (username, password) or an instance of HTTPBasicAuth.

Example: Basic Authentication

import requests
from requests.auth import HTTPBasicAuth

# The httpbin.org endpoint for basic auth is /basic-auth/user/passwd
target_url = 'https://httpbin.org/basic-auth/myuser/mypassword'
username = 'myuser'
password = 'mypassword'

try:
    # You can pass a tuple directly for auth
    # response = requests.get(target_url, auth=(username, password))

    # Or use the HTTPBasicAuth class explicitly
    response = requests.get(target_url, auth=HTTPBasicAuth(username, password))

    response.raise_for_status() # Check for HTTP errors
    print("Authentication successful!")
    print(response.json())
except requests.exceptions.HTTPError as e:
    print(f"Authentication failed or other HTTP error: {e.response.status_code} {e.response.reason}")
except requests.exceptions.RequestException as e:
    print(f"A request error occurred: {e}")

Expected Output

Authentication successful!
{'authenticated': True, 'user': 'myuser'}

If you provide incorrect credentials or try to access without authentication, httpbin.org would return a 401 Unauthorized status.

Digest Authentication

Digest Authentication is more secure than Basic Authentication because it doesn’t send the password in clear text. Instead, it uses a challenge-response mechanism involving hashing.

requests supports this via HTTPDigestAuth.

Example: Digest Authentication

import requests
from requests.auth import HTTPDigestAuth

# The httpbin.org endpoint for digest auth is /digest-auth/qop/user/passwd
# qop can be 'auth' or 'auth-int'
target_url = 'https://httpbin.org/digest-auth/auth/myuser/mypassword'
username = 'myuser'
password = 'mypassword'

try:
    response = requests.get(target_url, auth=HTTPDigestAuth(username, password))
    response.raise_for_status()
    print("Digest Authentication successful!")
    print(response.json())
except requests.exceptions.HTTPError as e:
    print(f"Authentication failed or other HTTP error: {e.response.status_code} {e.response.reason}")
except requests.exceptions.RequestException as e:
    print(f"A request error occurred: {e}")

Expected Output

Digest Authentication successful!
{'authenticated': True, 'user': 'myuser'}

OAuth 2.0 Authentication with requests-oauthlib

OAuth 2.0 is an open standard for access delegation, commonly used for third-party applications to access user data on web services without exposing user credentials. It’s more complex than Basic or Digest authentication.

The requests-oauthlib library integrates OAuth capabilities with requests. First, install it:

pip install requests-oauthlib

The OAuth 2.0 flow typically involves several steps: redirecting the user to an authorization server, the user granting permission, the authorization server redirecting back with an authorization code, and finally, the application exchanging this code for an access token. The access token is then used to make authenticated API requests.

For this example, we’ll focus on the first step: generating an authorization URL. You’ll need a client_id and often a client_secret obtained by registering your application with the OAuth provider (e.g., Google, GitHub, Twitter).

Example: Generating an OAuth 2.0 Authorization URL

from requests_oauthlib import OAuth2Session

# Replace with your actual client ID from the OAuth provider
client_id = 'YOUR_CLIENT_ID_HERE'
# The redirect URI must match one registered with your OAuth application
redirect_uri = 'https://your-app.com/callback'
# The authorization endpoint URL provided by the OAuth service
# For example, Google's is 'https://accounts.google.com/o/oauth2/v2/auth'
authorization_base_url = 'https://some-oauth-provider.com/oauth/authorize'
# Scopes define the permissions your application is requesting
scope = ['read', 'write']

# Create an OAuth2Session instance
oauth_session = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=scope)

# Generate the authorization URL and state
# The 'state' parameter is used to prevent CSRF attacks and should be stored by your app
authorization_url, state = oauth_session.authorization_url(authorization_base_url)

print('Please go to the following URL and authorize the application:')
print(authorization_url)
print(f'State parameter generated: {state}')

# In a real application:
# 1. Redirect the user to authorization_url.
# 2. User authorizes.
# 3. User is redirected back to your redirect_uri with a 'code' and 'state'.
# 4. Verify the 'state' matches the one you stored.
# 5. Fetch the token using:
#    token = oauth_session.fetch_token('TOKEN_URL', client_secret='YOUR_CLIENT_SECRET', code=CODE_FROM_REDIRECT)
# 6. Use the oauth_session (now with token) to make authenticated requests:
#    profile_response = oauth_session.get('https://api.some-oauth-provider.com/profile')

This code snippet only generates the URL. A full OAuth 2.0 implementation involves handling the redirect, exchanging the code for a token, and managing token refresh. requests-oauthlib greatly simplifies these tasks.

Expected Output (URL will vary based on parameters)

Please go to the following URL and authorize the application:
https://some-oauth-provider.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID_HERE&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&scope=read+write&state=GeneratedRandomStateValue
State parameter generated: GeneratedRandomStateValue

For more comprehensive examples and different OAuth 2.0 grant types, consult the requests-oauthlib documentation and the specific documentation of the OAuth provider you are integrating with.