OIDC auth middleware with GitHub Actions example workflow (#31)

* Add plugin helper entrypoint_style_load() to assist with loading auth middleware
* Add server CLI arg for Flask middleware loaded via entrypoint style load plugin helper
* OIDC auth middleware plugin
* Refactor test Service expose url with bound port to Flask app
* In preperation for use by flask test app used as OIDC endpoints
* Tests for OIDC based auth middleware
* Update pip, setuptools, wheel to avoid deprecation warning on dependency install.
* Example CI job for GitHub Actions OIDC authenticated notary
* Token is not available within pull_request context.
* Document OIDC authentication middleware usage with GitHub Actions
* Validation of OIDC claims via JSON schema validator

Related: slsa-framework/slsa-github-generator#131
Related: slsa-framework/slsa-github-generator#358
Related: actions/runner#2417 (comment)

Signed-off-by: John Andersen <johnandersenpdx@gmail.com>

Author: pdxjohnny

.github/workflows/notarize.yml

@@ -0,0 +1,128 @@
+name: "SCITT Notary"
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+  workflow_dispatch:
+    inputs:
+      scitt-url:
+        description: 'URL of SCITT instance'
+        type: string
+      payload:
+        description: 'Payload for claim'
+        default: ''
+        type: string
+  workflow_call:
+    inputs:
+      scitt-url:
+        description: 'URL of SCITT instance'
+        type: string
+      payload:
+        description: 'Payload for claim'
+        type: string
+
+jobs:
+  notarize:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    env:
+      SCITT_URL: '${{ inputs.scitt-url || github.event.inputs.scitt-url }}'
+      PAYLOAD: '${{ inputs.payload || github.event.inputs.payload }}'
+    steps:
+      - name: Set defaults if env vars not set (as happens with on.push trigger)
+        run: |
+          if [[ "x${SCITT_URL}" = "x" ]]; then
+            echo "SCITT_URL=http://localhost:8080" >> "${GITHUB_ENV}"
+          fi
+          if [[ "x${PAYLOAD}" = "x" ]]; then
+            echo 'PAYLOAD={"key": "value"}' >> "${GITHUB_ENV}"
+          fi
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.8
+      - name: Install SCITT API Emulator
+        run: |
+          pip install -U pip setuptools wheel
+          pip install .[oidc]
+      - name: Install github-script dependencies
+        run: |
+          npm install @actions/core
+      - name: Get OIDC token to use as bearer token for auth to SCITT
+        uses: actions/github-script@v6
+        id: github-oidc
+        with:
+          script: |
+            const {SCITT_URL} = process.env;
+            core.setOutput('token', await core.getIDToken(SCITT_URL));
+      - name: Create claim
+        run: |
+          scitt-emulator client create-claim --issuer did:web:example.org --content-type application/json --payload "${PAYLOAD}" --out claim.cose
+      - name: Submit claim
+        env:
+          OIDC_TOKEN: '${{ steps.github-oidc.outputs.token }}'
+          WORKFLOW_REF: '${{ github.workflow_ref }}'
+          # Use of job_workflow_sha blocked by
+          # https://github.com/actions/runner/issues/2417#issuecomment-1718369460
+          JOB_WORKFLOW_SHA: '${{ github.sha }}'
+          REPOSITORY_OWNER_ID: '${{ github.repository_owner_id }}'
+          REPOSITORY_ID: '${{ github.repository_id }}'
+        run: |
+          # Create the middleware config file
+          tee oidc-middleware-config.json <<EOF
+          {
+              "issuers": ["https://token.actions.githubusercontent.com"],
+              "claim_schema": {
+                  "https://token.actions.githubusercontent.com": {
+                        "\$schema": "https://json-schema.org/draft/2020-12/schema",
+                        "required": [
+                            "job_workflow_ref",
+                            "job_workflow_sha",
+                            "repository_owner_id",
+                            "repository_id"
+                        ],
+                        "properties": {
+                            "job_workflow_ref": {
+                                "type": "string",
+                                "enum": [
+                                    "${WORKFLOW_REF}"
+                                ]
+                            },
+                            "job_workflow_sha": {
+                                "type": "string",
+                                "enum": [
+                                    "${JOB_WORKFLOW_SHA}"
+                                ]
+                            },
+                            "repository_owner_id": {
+                                "type": "string",
+                                "enum": [
+                                    "${REPOSITORY_OWNER_ID}"
+                                ]
+                            },
+                            "repository_id": {
+                                "type": "string",
+                                "enum": [
+                                    "${REPOSITORY_ID}"
+                                ]
+                            }
+                        }
+                    }
+              },
+              "audience": "${SCITT_URL}"
+          }
+          EOF
+          # Start SCITT using the `OIDCAuthMiddleware` and associated config.
+          if [[ "x${SCITT_URL}" = "xhttp://localhost:8080" ]]; then
+            scitt-emulator server --port 8080 --workspace workspace/ --tree-alg CCF \
+              --middleware scitt_emulator.oidc:OIDCAuthMiddleware \
+              --middleware-config-path oidc-middleware-config.json &
+            sleep 1s
+          fi
+          # Submit the claim using OIDC token as auth
+          scitt-emulator client submit-claim --token "${OIDC_TOKEN}" --url "${SCITT_URL}" --claim claim.cose --out claim.receipt.cbor

dev-requirements.txt

@@ -5,3 +5,5 @@ requests==2.31.0
 requests-toolbelt==0.9
 urllib3<2.0.0
 myst-parser
+PyJWT
+jwcrypto

docs/oidc.md

@@ -0,0 +1,23 @@
+# OIDC Support
+
+- References
+  - [5.1.1.1.1.](https://github.com/ietf-wg-scitt/draft-ietf-scitt-architecture/blob/main/draft-ietf-scitt-architecture.md#comment-on-oidc)
+
+[![asciicast-of-oidc-auth-issued-by-github-actions](https://asciinema.org/a/607600.svg)](https://asciinema.org/a/607600)
+
+## Dependencies
+
+Install the SCITT API Emulator with the `oidc` extra.
+
+```console
+$ pip install -e .[oidc]
+```
+
+## Usage example with GitHub Actions
+
+See [`notarize.yml`](../.github/workflows/notarize.yml)
+
+References:
+
+- https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows
+- https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect

environment.yml

@@ -36,3 +36,5 @@ dependencies:
     - urllib3<2.0.0
     - myst-parser==1.0.0
     - jsonschema==4.17.3
+    - jwcrypto==1.5.0
+    - PyJWT==2.8.0

run-tests.sh

@@ -8,8 +8,9 @@ if [ ! -f "venv/bin/activate" ]; then
     echo "Setting up Python virtual environment."
     python3 -m venv "venv"
     . ./venv/bin/activate
+    pip install -q -U pip setuptools wheel
     pip install -q -r dev-requirements.txt
-    pip install -q -e .
+    pip install -q -e .[oidc]
 else
     . ./venv/bin/activate 
 fi

scitt_emulator/oidc.py

@@ -0,0 +1,51 @@
+# Copyright (c) SCITT Authors.
+# Licensed under the MIT License.
+import jwt
+import json
+import jwcrypto.jwk
+import jsonschema
+from flask import jsonify
+from werkzeug.wrappers import Request
+from scitt_emulator.client import HttpClient
+
+
+class OIDCAuthMiddleware:
+    def __init__(self, app, config_path):
+        self.app = app
+        self.config = {}
+        if config_path and config_path.exists():
+            self.config = json.loads(config_path.read_text())
+
+        # Initialize JSON Web Key client for given issuer
+        self.client = HttpClient()
+        self.oidc_configs = {}
+        self.jwks_clients = {}
+        for issuer in self.config['issuers']:
+            self.oidc_configs[issuer] = self.client.get(
+                f"{issuer}/.well-known/openid-configuration"
+            ).json()
+            self.jwks_clients[issuer] = jwt.PyJWKClient(self.oidc_configs[issuer]["jwks_uri"])
+
+    def __call__(self, environ, start_response):
+        request = Request(environ)
+        claims = self.validate_token(request.headers["Authorization"].replace("Bearer ", ""))
+        if "claim_schema" in self.config and claims["iss"] in self.config["claim_schema"]:
+            jsonschema.validate(claims, schema=self.config["claim_schema"][claims["iss"]])
+        return self.app(environ, start_response)
+
+    def validate_token(self, token):
+        validation_error = Exception(f"Failed to validate against all issuers: {self.jwks_clients.keys()!s}")
+        for issuer, jwk_client in self.jwks_clients.items():
+            try:
+                return jwt.decode(
+                    token,
+                    key=jwk_client.get_signing_key_from_jwt(token).key,
+                    algorithms=self.oidc_configs[issuer]["id_token_signing_alg_values_supported"],
+                    audience=self.config.get("audience", None),
+                    issuer=self.oidc_configs[issuer]["issuer"],
+                    options={"strict_aud": self.config.get("strict_aud", True),},
+                    leeway=self.config.get("leeway", 0),
+                )
+            except jwt.PyJWTError as error:
+                validation_error = error
+        raise validation_error

scitt_emulator/plugin_helpers.py

@@ -0,0 +1,36 @@
+# Copyright (c) SCITT Authors.
+# Licensed under the MIT License.
+import os
+import sys
+import pathlib
+import importlib
+from typing import Iterator, Optional, Union, Any
+
+
+def entrypoint_style_load(
+    *args: str, relative: Optional[Union[str, pathlib.Path]] = None
+) -> Iterator[Any]:
+    """
+    Load objects given the entrypoint formatted path to the object. Roughly how
+    the python stdlib docs say entrypoint loading works.
+    """
+    # Push current directory into front of path so we can run things
+    # relative to where we are in the shell
+    if relative is not None:
+        if relative == True:
+            relative = os.getcwd()
+        # str() in case of Path object
+        sys.path.insert(0, str(relative))
+    try:
+        for entry in args:
+            modname, qualname_separator, qualname = entry.partition(":")
+            obj = importlib.import_module(modname)
+            for attr in qualname.split("."):
+                if hasattr(obj, "__getitem__"):
+                    obj = obj[attr]
+                else:
+                    obj = getattr(obj, attr)
+            yield obj
+    finally:
+        if relative is not None:
+            sys.path.pop(0)

scitt_emulator/server.py

@@ -9,6 +9,7 @@
 from flask import Flask, request, send_file, make_response
 
 from scitt_emulator.tree_algs import TREE_ALGS
+from scitt_emulator.plugin_helpers import entrypoint_style_load
 from scitt_emulator.scitt import EntryNotFoundError, ClaimInvalidError, OperationNotFoundError
 
 
@@ -33,6 +34,9 @@ def create_flask_app(config):
     app.config.update(dict(DEBUG=True))
     app.config.update(config)
 
+    if app.config.get("middleware", None):
+        app.wsgi_app = app.config["middleware"](app.wsgi_app, app.config.get("middleware_config_path", None))
+
     error_rate = app.config["error_rate"]
     use_lro = app.config["use_lro"]
 
@@ -117,10 +121,18 @@ def cli(fn):
     parser.add_argument("--use-lro", action="store_true", help="Create operations for submissions")
     parser.add_argument("--tree-alg", required=True, choices=list(TREE_ALGS.keys()))
     parser.add_argument("--workspace", type=Path, default=Path("workspace"))
+    parser.add_argument(
+        "--middleware",
+        type=lambda value: list(entrypoint_style_load(value))[0],
+        default=None,
+    )
+    parser.add_argument("--middleware-config-path", type=Path, default=None)
 
     def cmd(args):
         app = create_flask_app(
             {
+                "middleware": args.middleware,
+                "middleware_config_path": args.middleware_config_path,
                 "tree_alg": args.tree_alg,
                 "workspace": args.workspace,
                 "error_rate": args.error_rate,

setup.py

@@ -21,4 +21,11 @@
         "flask",
         "rkvst-archivist"
     ],
+    extras_require={
+        "oidc": [
+            "PyJWT",
+            "jwcrypto",
+            "jsonschema",
+        ]
+    },
 )

tests/test_cli.py

@@ -1,10 +1,15 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 import os
+import json
 import threading
 import pytest
+import jwt
+import jwcrypto
+from flask import Flask, jsonify
 from werkzeug.serving import make_server
 from scitt_emulator import cli, server
+from scitt_emulator.oidc import OIDCAuthMiddleware
 
 issuer = "did:web:example.com"
 content_type = "application/json"
@@ -16,16 +21,23 @@ def execute_cli(argv):
 
 
 class Service:
-    def __init__(self, config):
+    def __init__(self, config, create_flask_app=None):
         self.config = config
+        self.create_flask_app = (
+            create_flask_app
+            if create_flask_app is not None
+            else server.create_flask_app
+        )
 
     def __enter__(self):
-        app = server.create_flask_app(self.config)
-        self.service_parameters_path = app.service_parameters_path
-        host = "127.0.0.1"
-        self.server = make_server(host, 0, app)
+        app = self.create_flask_app(self.config)
+        if hasattr(app, "service_parameters_path"):
+            self.service_parameters_path = app.service_parameters_path
+        self.host = "127.0.0.1"
+        self.server = make_server(self.host, 0, app)
         port = self.server.port
-        self.url = f"http://{host}:{port}"
+        self.url = f"http://{self.host}:{port}"
+        app.url = self.url
         self.thread = threading.Thread(name="server", target=self.server.serve_forever)
         self.thread.start()
         return self
@@ -142,3 +154,160 @@ def test_client_cli(use_lro: bool, tmp_path):
         with open(receipt_path_2, "rb") as f:
             receipt_2 = f.read()
         assert receipt == receipt_2
+
+
+def create_flask_app_oidc_server(config):
+    app = Flask("oidc_server")
+
+    app.config.update(dict(DEBUG=True))
+    app.config.update(config)
+
+    @app.route("/.well-known/openid-configuration", methods=["GET"])
+    def openid_configuration():
+        return jsonify(
+            {
+                "issuer": app.url,
+                "jwks_uri": f"{app.url}/.well-known/jwks",
+                "response_types_supported": ["id_token"],
+                "claims_supported": ["sub", "aud", "exp", "iat", "iss"],
+                "id_token_signing_alg_values_supported": app.config["algorithms"],
+                "scopes_supported": ["openid"],
+            }
+        )
+
+    @app.route("/.well-known/jwks", methods=["GET"])
+    def jwks():
+        return jsonify(
+            {
+                "keys": [
+                    {
+                        **app.config["key"].export_public(as_dict=True),
+                        "use": "sig",
+                        "kid": app.config["key"].thumbprint(),
+                    }
+                ]
+            }
+        )
+
+    return app
+
+
+def test_client_cli_token(tmp_path):
+    workspace_path = tmp_path / "workspace"
+
+    claim_path = tmp_path / "claim.cose"
+    receipt_path = tmp_path / "claim.receipt.cbor"
+    entry_id_path = tmp_path / "claim.entry_id.txt"
+    retrieved_claim_path = tmp_path / "claim.retrieved.cose"
+
+    key = jwcrypto.jwk.JWK.generate(kty="RSA", size=2048)
+    algorithm = "RS256"
+    audience = "scitt.example.org"
+    subject = "repo:scitt-community/scitt-api-emulator:ref:refs/heads/main"
+
+    with Service(
+        {"key": key, "algorithms": [algorithm]},
+        create_flask_app=create_flask_app_oidc_server,
+    ) as oidc_service:
+        os.environ["no_proxy"] = ",".join(
+            os.environ.get("no_proxy", "").split(",") + [oidc_service.host]
+        )
+        middleware_config_path = tmp_path / "oidc-middleware-config.json"
+        middleware_config_path.write_text(
+            json.dumps(
+                {
+                    "issuers": [oidc_service.url],
+                    "audience": audience,
+                    "claim_schema": {
+                        oidc_service.url: {
+                            "$schema": "https://json-schema.org/draft/2020-12/schema",
+                            "required": ["sub"],
+                            "properties": {
+                                "sub": {"type": "string", "enum": [subject]},
+                            },
+                        }
+                    },
+                }
+            )
+        )
+        with Service(
+            {
+                "middleware": OIDCAuthMiddleware,
+                "middleware_config_path": middleware_config_path,
+                "tree_alg": "CCF",
+                "workspace": workspace_path,
+                "error_rate": 0.1,
+                "use_lro": False,
+            }
+        ) as service:
+            # create claim
+            command = [
+                "client",
+                "create-claim",
+                "--out",
+                claim_path,
+                "--issuer",
+                issuer,
+                "--content-type",
+                content_type,
+                "--payload",
+                payload,
+            ]
+            execute_cli(command)
+            assert os.path.exists(claim_path)
+
+            # submit claim without token
+            command = [
+                "client",
+                "submit-claim",
+                "--claim",
+                claim_path,
+                "--out",
+                receipt_path,
+                "--out-entry-id",
+                entry_id_path,
+                "--url",
+                service.url,
+            ]
+            check_error = None
+            try:
+                execute_cli(command)
+            except Exception as error:
+                check_error = error
+            assert check_error
+            assert not os.path.exists(receipt_path)
+            assert not os.path.exists(entry_id_path)
+
+            # create token without subject
+            token = jwt.encode(
+                {"iss": oidc_service.url, "aud": audience},
+                key.export_to_pem(private_key=True, password=None),
+                algorithm=algorithm,
+                headers={"kid": key.thumbprint()},
+            )
+            # submit claim with token lacking subject
+            command += [
+                "--token",
+                token,
+            ]
+            check_error = None
+            try:
+                execute_cli(command)
+            except Exception as error:
+                check_error = error
+            assert check_error
+            assert not os.path.exists(receipt_path)
+            assert not os.path.exists(entry_id_path)
+
+            # create token with subject
+            token = jwt.encode(
+                {"iss": oidc_service.url, "aud": audience, "sub": subject},
+                key.export_to_pem(private_key=True, password=None),
+                algorithm=algorithm,
+                headers={"kid": key.thumbprint()},
+            )
+            # submit claim with token containing subject
+            command[-1] = token
+            execute_cli(command)
+            assert os.path.exists(receipt_path)
+            assert os.path.exists(entry_id_path)

tests/test_plugin_helpers.py

@@ -0,0 +1,55 @@
+# Copyright (c) SCITT Authors.
+# Licensed under the MIT License.
+import os
+import textwrap
+
+from scitt_emulator.plugin_helpers import entrypoint_style_load
+
+
+def test_entrypoint_style_load_relative(tmp_path):
+    plugin_path = tmp_path / "myplugin.py"
+
+    plugin_path.write_text(
+        textwrap.dedent(
+            """
+            def my_cool_plugin():
+                return "Hello World"
+
+
+            class MyCoolClass:
+                @staticmethod
+                def my_cool_plugin():
+                    return my_cool_plugin()
+
+
+            my_cool_dict = {
+                "my_cool_plugin": my_cool_plugin,
+            }
+            """,
+        )
+    )
+
+    for load_within_file in [
+        "my_cool_plugin",
+        "MyCoolClass.my_cool_plugin",
+        "my_cool_dict.my_cool_plugin",
+    ]:
+        plugin_entrypoint_style_path = (
+            str(plugin_path.relative_to(tmp_path).with_suffix("")).replace(
+                os.path.sep, "."
+            )
+            + ":"
+            + load_within_file
+        )
+
+        loaded = list(
+            entrypoint_style_load(plugin_entrypoint_style_path, relative=tmp_path)
+        )[0]
+
+        os.chdir(tmp_path)
+
+        loaded = list(
+            entrypoint_style_load(plugin_entrypoint_style_path, relative=True)
+        )[0]
+
+        assert loaded() == "Hello World"