OpenID Connect Provider (OP) library for Python

Common errors

• pymongo.errors.CollectionInvalid: collection names must not start or end with '.' or contain '$'

  cause This error typically indicates an incompatibility between an older version of pyop's MongoStorage and PyMongo 4, which has stricter naming conventions.
  fix Upgrade pyop to version 3.4.1 or higher to ensure compatibility with PyMongo 4. Alternatively, if you cannot upgrade pyop, downgrade your PyMongo version to 3.x.

• AttributeError: 'Server' object has no attribute 'get_additional_scopes'

  cause This error or similar issues related to custom scope handling often arise after upgrading to pyop v3.0.0 due to a breaking change in how additional scopes are managed.
  fix The 'additional scopes' feature was re-implemented in a non-backwards compatible way in v3.0.0. Consult the release notes for v3.0.0 and update your custom scope definition and retrieval logic accordingly.

• TypeError: argument of type 'NoneType' is not iterable in userinfo handling

  cause A bug existed in pyop versions prior to 3.4.1 where userinfo handling in stateless mode could lead to `TypeError` if a user ID was `None`.
  fix Upgrade pyop to version 3.4.1 or higher to resolve the bug related to `None` user IDs in stateless userinfo handling.

Warnings

• breaking Version 3.0.0 reverted support for 'additional scopes' introduced in v2.1.0 and reimplemented it in a non-backwards compatible way.
  Fix: Review the v3.0.0 release notes and update any custom scope handling logic to align with the new implementation. Be prepared for changes in how custom scopes are defined and processed.
• gotcha When using PKCE support (introduced in v3.3.0), the library explicitly states that 'plaintext support is missing'.
  Fix: Ensure that your client applications use S256 (SHA256) as the code challenge method for PKCE, as plaintext (plain) is not supported by pyop.
• gotcha Prior to v3.4.1, pyop had compatibility issues with PyMongo 4, potentially leading to errors when using MongoStorage.
  Fix: Upgrade to pyop version 3.4.1 or newer if you are using PyMongo 4. Alternatively, downgrade PyMongo to a compatible version (e.g., PyMongo 3.x) for older pyop versions.
• gotcha Version 3.4.0 introduced support for a stateless code flow. If your application relies on stateful operations, upgrading might require attention to ensure existing state management patterns are compatible or if explicit stateless handling is desired.
  Fix: Review the documentation for the stateless code flow in v3.4.0+. If your application implicitly relied on state for certain operations, verify behavior or explicitly configure state management as needed.

Install

• pip install pyop Basic Install
• pip install pyop[mongo] Install with MongoDB support
• pip install pyop[redis] Install with Redis support

Imports

• Server
  wrong:

  from pyop import Server

  correct:

  from pyop.server import Server

  The Server class resides in the 'server' submodule, not directly under 'pyop'.
• DictStorage
  wrong:

  from pyop.server.storage import DictStorage

  correct:

  from pyop.storage import DictStorage

  Storage backends are in the 'storage' submodule.

Quickstart

This quickstart demonstrates how to initialize a basic pyop OpenID Connect Provider (OP) server using an in-memory dictionary storage. It sets up essential configuration like the issuer, JWKS URI, supported response types, and client information. For production environments, you would replace `DictStorage` with a persistent storage solution (e.g., `MongoStorage`, `RedisStorage`) and integrate the `Server` instance with your web framework (e.g., Flask, Django) to handle incoming OIDC requests at appropriate endpoints.

import os
from pyop.server import Server
from pyop.storage import DictStorage

def create_op_server():
    # In a real application, configuration would be loaded from a file or environment
    OP_BASE_URL = os.environ.get('OP_BASE_URL', 'http://localhost:8090')
    JWKS_URI = f'{OP_BASE_URL}/jwks.json'

    # Client information (for registered clients)
    # In a real scenario, this would come from a client registration process/database
    CLIENTS = {
        'test_client': {
            'client_id': 'test_client',
            'client_secret': 'test_secret',
            'redirect_uris': ['http://localhost:8000/cb'],
            'response_types': ['code', 'id_token', 'code id_token'],
            'scope': ['openid', 'profile', 'email'],
            'subject_type': 'pairwise'
        }
    }

    # In-memory storage for demonstration purposes
    # For production, use MongoStorage, RedisStorage, or a custom persistent storage
    storage = DictStorage()
    storage.store_clients(CLIENTS)

    # Minimal server configuration
    server_config = {
        'issuer': OP_BASE_URL,
        'jwks_uri': JWKS_URI,
        'authentication_methods': ['client_secret_basic'],
        'response_types_supported': ['code', 'id_token', 'code id_token'],
        'subject_types_supported': ['pairwise'],
        'scopes_supported': ['openid', 'profile', 'email'],
        'claims_supported': ['sub', 'name', 'email', 'given_name', 'family_name']
    }

    op_server = Server(server_config, storage)
    print(f"OpenID Connect Provider Server initialized with issuer: {op_server.configuration.issuer}")
    return op_server

if __name__ == '__main__':
    # Example usage: this only initializes the server, does not run a web server.
    # A production app would integrate this into Flask, Django, FastAPI, etc.
    # Example: op_server.handle_authentication_request(request_params, session_id)
    op = create_op_server()
    # You would then integrate 'op' with your web framework to handle OIDC endpoints.