ckanext-oidc4vc

CKAN extension to authenticate users with an OIDC4VC-compatible provider.

It implements:

• OIDC login redirect and callback endpoints
• Access token exchange and JWT signature verification via provider JWKS
• User extraction from token claims (including claim paths with list index support)
• Automatic CKAN user provisioning
• Automatic organization provisioning and membership assignment from credential claims

Compatibility

• CKAN: 2.11 (current target)
• Python: 3.10

Endpoints

• Login: /user/login/oidc4vc
• Callback: /auth/oidc4vc/callback

Installation

To install ckanext-oidc4vc:

1. Activate your CKAN virtual environment:

   . /usr/lib/ckan/default/bin/activate

2. Install the extension:

   git clone https://github.com/SEAMWARE/ckanext-oidc4vc.git
   cd ckanext-oidc4vc
   pip install -e .
   pip install -r requirements.txt

3. Enable the plugin in CKAN config:

   ckan.plugins = ... oidc4vc ...

4. Restart CKAN.

Configuration

You can configure values via CKAN config (ckanext.oidc4vc.*) or environment variables (CKANEXT_OIDC4VC_*).

Required

• ckanext.oidc4vc.issuer / CKANEXT_OIDC4VC_ISSUER
  • Base issuer URL (for example https://verifier.example.org)
• ckanext.oidc4vc.client_id / CKANEXT_OIDC4VC_CLIENT_ID
• ckanext.oidc4vc.redirect_uri / CKANEXT_OIDC4VC_REDIRECT_URI
  • Path appended to ckan.site_url (for example /auth/oidc4vc/callback)
• ckanext.oidc4vc.scopes / CKANEXT_OIDC4VC_SCOPES
• ckanext.oidc4vc.email_claim / CKANEXT_OIDC4VC_EMAIL_CLAIM
• ckanext.oidc4vc.first_name_claim / CKANEXT_OIDC4VC_FIRST_NAME_CLAIM
• ckanext.oidc4vc.last_name_claim / CKANEXT_OIDC4VC_LAST_NAME_CLAIM
• ckanext.oidc4vc.org_id_claim / CKANEXT_OIDC4VC_ORG_ID_CLAIM
• ckanext.oidc4vc.roles_claim / CKANEXT_OIDC4VC_ROLES_CLAIM
• ckanext.oidc4vc.editor_role / CKANEXT_OIDC4VC_EDITOR_ROLE
• ckanext.oidc4vc.org_admin_role / CKANEXT_OIDC4VC_ORG_ADMIN_ROLE

Optional

• ckanext.oidc4vc.auth_path / CKANEXT_OIDC4VC_AUTH_PATH
  • If set, login authorization URL is issuer + auth_path
  • If unset, authorization endpoint comes from discovery
• ckanext.oidc4vc.token_path / CKANEXT_OIDC4VC_TOKEN_PATH
  • If set, token URL is issuer + token_path
  • If unset, token endpoint comes from discovery
• ckanext.oidc4vc.discovery_client_base_path / CKANEXT_OIDC4VC_DISCOVERY_CLIENT_BASE_PATH
  • Default: /services
  • Used to build client-specific discovery URL

Discovery behavior

Discovery tries URLs in this order:

1. {issuer}{discovery_client_base_path}/{client_id}/.well-known/openid-configuration
2. {issuer}/.well-known/openid-configuration

JWKS URI is read from discovery (jwks_uri), and signing keys are cached.

Claim path syntax

Claim paths support:

• dot notation, e.g. a.b.c
• single list index per segment, e.g. verifiableCredential[0].credentialSubject.email

Unsupported pattern example: a[0][1].x

Example (environment variables)

CKANEXT_OIDC4VC_ISSUER=https://verifier.example.org
CKANEXT_OIDC4VC_CLIENT_ID=data-service
CKANEXT_OIDC4VC_REDIRECT_URI=/auth/oidc4vc/callback
CKANEXT_OIDC4VC_SCOPES=operator
CKANEXT_OIDC4VC_EMAIL_CLAIM=verifiableCredential[0].credentialSubject.email
CKANEXT_OIDC4VC_FIRST_NAME_CLAIM=verifiableCredential[0].credentialSubject.firstName
CKANEXT_OIDC4VC_LAST_NAME_CLAIM=verifiableCredential[0].credentialSubject.lastName
CKANEXT_OIDC4VC_ORG_ID_CLAIM=verifiableCredential[0].issuer
CKANEXT_OIDC4VC_ROLES_CLAIM=verifiableCredential[0].credentialSubject.roles
CKANEXT_OIDC4VC_EDITOR_ROLE=ckan:editor
CKANEXT_OIDC4VC_ORG_ADMIN_ROLE=ckan:admin

Security notes

• Access token JWT signature is verified against JWKS.
• Audience validation is currently disabled (verify_aud=False).
• If your provider supports id_token, validating issuer/audience explicitly is recommended.

Developer installation

git clone https://github.com/SEAMWARE/ckanext-oidc4vc.git
cd ckanext-oidc4vc
pip install -e .
pip install -r dev-requirements.txt

Tests

Run all tests:

pytest --ckan-ini=test.ini

Run unit tests only:

pytest --ckan-ini=test.ini ckanext/oidc4vc/tests/unit

Releasing a new version of ckanext-oidc4vc

1. Update version in pyproject.toml

2. Build and validate distribution:

   python -m build && twine check dist/*

3. Upload to PyPI:

   twine upload dist/*

4. Commit and tag:

   git commit -a -m "Release x.y.z"
   git push
   git tag x.y.z
   git push --tags

License

AGPL