Welcome to Requests-OIDC’s documentation!

Implements a simple API for creating a requests Session that manages your OIDC-discovered OAuth2 session for you.

pip install requests-oidc

from requests_oidc import make_auth_code_session
from requests_oidc.plugins import OSCachedPlugin

oidc_url = "https://your-oidc-provider.com/.well-known/openid-configuration"
client_id = "your-app"
port = 8675
scope = ["openid", "email", "profile"]

plugin = OSCachedPlugin("your-app", "your-company")



session = make_auth_code_session(oidc_url, client_id, port, scope, plugin=plugin)

Package

PyPI GitHub PyPI - Status PyPI - Format PyPI - Python Version PyPI - Implementation PyPI - Downloads

build

GitHub branch checks state Read the Docs Coverage

Git

GitHub last commit GitHub commit activity GitHub commits since latest release (by SemVer) GitHub issues GitHub pull requests

Flows

requests_oidc.make_auth_code_session(oidc_url: str, client_id: str, port: int, scope: ~typing.List[str] | None = None, *, klass=<class 'requests_oauthlib.oauth2_session.OAuth2Session'>, plugin: ~requests_oidc.types.Plugin | None = None, **kwargs) → OAuth2Session

Create an OAuth2Session via web redirect, w/ automatic token management.

After it is created, this session will behave as a regular requests.Session object, that injects the access token as an Authorization header. Do not use that session to call APIs that aren’t the one you authenticated for, as that will leak your access token to third parties.

To use this function, you’ll need a public client w/ a redirect_uri set to http://localhost:{port}/callback. Pick a unique port per client. Sharing the same one across different tools may work, but it’s a bad assumption to rely on.

The (client_id, port) tuple can be treated as constants within your code, and distributed as part of tooling that is built using this module.

Parameters:

  • oidc_url – Path to an openid-connect server’s .well-known/openid-configuration.

  • client_id – Public client ID. This must be a public client w/o a secret.

  • port – Port on localhost to redirect to from the auth server. http://localhost:{port}/callback must be a permitted redirect_uri for your client or the auth server will refuse to service your auth request.

  • updater – Optional callback function to invoke whenever a token is fetched. This includes the first token fetch, and all refetches thereafter.

requests_oidc.make_device_code_session(oidc_url: str, client_id: str, audience: str, token: dict | None = None, scope: ~typing.List[str] | None = None, *, klass=<class 'requests_oauthlib.oauth2_session.OAuth2Session'>, plugin: ~requests_oidc.types.Plugin | None = None, **kwargs)
requests_oidc.make_client_credentials_session(oidc_url: str, client_id: str, client_secret: str, scope: ~typing.List[str] | None = None, *, klass=<class 'requests_oauthlib.oauth2_session.OAuth2Session'>, plugin: ~requests_oidc.types.Plugin | None = None, **kwargs) → OAuth2Session
requests_oidc.make_token_session(oidc_url: str, client_id: str, scope: ~typing.List[str] | None = None, *, klass=<class 'requests_oauthlib.oauth2_session.OAuth2Session'>, plugin: ~requests_oidc.types.Plugin | None = None, **kwargs) → OAuth2Session

Plugins

class requests_oidc.plugins.PathPlugin(path: Path, *, noload: bool = False, nostore: bool = False)

Plugin to load / store files to an OS path location

class requests_oidc.plugins.OSCachedPlugin(appname: str, appauthor: str, version: str | None = None, filename: str = 'token.json', *, noload: bool = False, nostore: bool = False)

Same as PathPlugin, but saves/loads to the OS’s user-cache directory (appdata, ~/.cache/…, etc).