fastapi-zitadel-auth 0.1.0__tar.gz

fastapi_zitadel_auth-0.1.0/.codecov.yml

@@ -0,0 +1,16 @@
+codecov:
+  require_ci_to_pass: yes
+
+coverage:
+  precision: 1
+  round: down
+  status:
+    project:
+      default:
+        target: auto
+    patch: no
+    changes: no
+
+comment:
+  layout: "diff,files"
+  require_changes: yes

fastapi_zitadel_auth-0.1.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "09:00"
+      timezone: "Europe/Zurich"
+    commit-message:
+      prefix: "deps(actions):"
+
+  # uv dependabot for uv.lock not yet available, see https://docs.astral.sh/uv/guides/integration/dependency-bots/#dependabot
+#  - package-ecosystem: "pip"
+#    schedule:
+#      interval: "weekly"
+#      time: "09:00"
+#      timezone: "Europe/Zurich"
+#    commit-message:
+#      prefix: "deps(api):"

fastapi_zitadel_auth-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,54 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  schedule:
+    - cron: '15 7 * * 1'  # 07:15 Monday
+
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: python
+          build-mode: none
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+
+    - if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

fastapi_zitadel_auth-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  release:
+    types: [ published ]
+
+permissions:
+  id-token: write  # Required for trusted publishing
+  contents: read   # Required for checkout
+
+jobs:
+  run:
+    name: Build and publish release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build
+        run: uv build
+
+      # Using Trusted Publishing via PyPI and uv
+      - name: Debug and Publish
+        run: |
+          echo "Current directory: $(pwd)"
+          echo "Workflow file contents:"
+          cat .github/workflows/publish.yml
+          echo "Environment variables:"
+          env | grep -i action
+          echo "Running publish command..."
+          uv publish --verbose --trusted-publishing always

fastapi_zitadel_auth-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on: pull_request
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run tests
+        run: |
+          uv run pytest tests/ -v --cov=src --cov-report=xml
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}

fastapi_zitadel_auth-0.1.0/.gitignore

@@ -0,0 +1,166 @@
+.idea/
+# private key file from Zitadel
+*.json
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

fastapi_zitadel_auth-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+exclude: README.md
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.1
+    hooks:
+      - id: ruff
+        entry: uv run ruff check src/
+        files: \.py$
+      - id: ruff-format
+        entry: uv run ruff format src/
+        files: \.py$
+
+  - repo: https://github.com/econchick/interrogate
+    rev: 1.7.0
+    hooks:
+      - id: interrogate
+        args: [-vv, tests]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-yaml

fastapi_zitadel_auth-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

fastapi_zitadel_auth-0.1.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Clean Energy Exchange GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_zitadel_auth-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.3
+Name: fastapi-zitadel-auth
+Version: 0.1.0
+Summary: Zitadel authentication for FastAPI
+Author-email: Clean Energy Exchange <info@ceex.ch>
+Keywords: async,asyncio,authentication,fastapi,oauth,oidc,zitadel
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: cachetools>=5.5.0
+Requires-Dist: cryptography>=43.0.3
+Requires-Dist: fastapi>=0.115.4
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pyjwt>=2.9.0
+Description-Content-Type: text/markdown
+
+# FastAPI Zitadel Auth
+
+FastAPI Zitadel Auth is a Python package that simplifies OAuth2/OIDC authentication in FastAPI applications 
+using [Zitadel](https://zitadel.com/) as the identity provider.
+It handles token validation, role-based access control, and Swagger UI integration with just a few lines of code.
+
+<a href="https://github.com/cleanenergyexchange/fastapi-zitadel-auth/actions/workflows/test.yml" target="_blank">
+    <img src="https://github.com/cleanenergyexchange/fastapi-zitadel-auth/actions/workflows/test.yml/badge.svg" alt="Test status">
+</a>
+<a href="https://codecov.io/gh/cleanenergyexchange/fastapi-zitadel-auth">
+    <img src="https://codecov.io/gh/cleanenergyexchange/fastapi-zitadel-auth/graph/badge.svg?token=A3TSXDVLQT" alt="Code coverage"/> 
+</a>
+<a href="https://pypi.org/project/fastapi-zitadel-auth" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/fastapi-zitadel-auth.svg?color=%2334D058" alt="Supported Python versions">
+</a>
+<a href="https://pypi.org/pypi/fastapi-zitadel-auth">
+    <img src="https://img.shields.io/pypi/v/fastapi-zitadel-auth.svg?logo=pypi&logoColor=white&label=pypi" alt="Package version">
+</a>
+
+## Features
+
+* Authorization Code Flow with PKCE
+* JWT signature validation using JWKS obtained from Zitadel
+* Service User authentication using JWT Profiles
+* Swagger UI integration
+* Zitadel roles as scopes
+
+
+> [!NOTE]
+> This library implements JWT, locally validated using JWKS, as it prioritizes performance, 
+> see [Zitadel docs on Opaque tokens vs JWT](https://zitadel.com/docs/concepts/knowledge/opaque-tokens#use-cases-and-trade-offs).
+> If you need to validate opaque tokens using Introspection, please open an issue – PRs are welcome!
+
+
+## Installation and quick start
+
+```bash
+pip install fastapi-zitadel-auth
+```
+
+```python
+from fastapi import FastAPI, Security
+from fastapi_zitadel_auth import ZitadelAuth, AuthConfig
+
+auth = ZitadelAuth(AuthConfig(
+    client_id="your-client-id",
+    project_id="your-project-id",
+    base_url="https://your-instance.zitadel.cloud"
+))
+
+app = FastAPI()
+
+@app.get("/protected", dependencies=[Security(auth)])
+def protected_route():
+    return {"message": "Access granted!"}
+```
+
+See the [Usage](#usage) section for more details.
+
+## Usage
+
+### Configuration
+
+#### Zitadel
+
+Set up a new OAuth2 client in Zitadel according to the [docs/ZITADEL_SETUP.md](docs/ZITADEL_SETUP.md).
+
+#### FastAPI
+
+```python
+from fastapi import FastAPI, Request, Security
+from fastapi_zitadel_auth import ZitadelAuth, AuthConfig
+
+# Your Zitadel configuration
+CLIENT_ID = 'your-zitadel-client-id'
+PROJECT_ID = 'your-zitadel-project-id'
+BASE_URL = 'https://your-instance-xyz.zitadel.cloud'
+
+# Create an AuthConfig object with your Zitadel configuration
+config = AuthConfig(
+    client_id=CLIENT_ID,
+    project_id=PROJECT_ID,
+    base_url=BASE_URL,
+    scopes={
+        "openid": "OpenID Connect",
+        "email": "Email",
+        "profile": "Profile",
+        "urn:zitadel:iam:org:project:id:zitadel:aud": "Audience",
+        "urn:zitadel:iam:org:projects:roles": "Roles",
+    },
+)
+
+# Create a ZitadelAuth object with the AuthConfig usable as a FastAPI dependency
+auth = ZitadelAuth(config)
+
+# Create a FastAPI app and configure Swagger UI
+app = FastAPI(
+    title="fastapi-zitadel-auth demo",
+    swagger_ui_oauth2_redirect_url="/oauth2-redirect",
+    swagger_ui_init_oauth={
+        "usePkceWithAuthorizationCodeGrant": True,
+        "clientId": CLIENT_ID,
+        "scopes": " ".join(
+            [
+                "openid",
+                "email",
+                "profile",
+                "urn:zitadel:iam:org:project:id:zitadel:aud",
+                "urn:zitadel:iam:org:projects:roles",
+            ]
+        ),
+    },
+)
+
+# Create an endpoint and protect it with the ZitadelAuth dependency
+@app.get(
+    "/api/private",
+    summary="Private endpoint, requiring a valid token with `system` scope",
+    dependencies=[Security(auth, scopes=["system"])],
+)
+def private(request: Request):
+    return {
+        "message": f"Hello, protected world! Here is Zitadel user {request.state.user.user_id}"
+    }
+
+```
+
+## Demo app
+
+See `demo_project` for a complete example, including service user login. To run the demo app:
+
+```bash
+uv run demo_project/server.py
+```
+
+Then navigate to `http://localhost:8001/docs` to see the Swagger UI.
+
+
+### Service user
+
+Service users are "machine users" in Zitadel.
+
+To log in as a service user, change the config in `demo_project/service_user.py`, then
+
+```bash
+uv run demo_project/service_user.py
+```
+
+Make sure you have a running server at `http://localhost:8001`.
+
+## Development
+
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for development instructions.