auth-playground 0.0.1__py3-none-any.whl

auth_playground/__init__.py

@@ -0,0 +1,157 @@
+import importlib.metadata
+import os
+
+from authlib.integrations.flask_client import OAuth
+from authlib.oidc.discovery import get_well_known_url
+from cachelib.simple import SimpleCache
+from flask import Flask
+from flask import g
+from flask import has_request_context
+from flask import redirect
+from flask import request
+from flask import session as flask_session
+from flask import url_for
+from flask_session import Session
+
+from auth_playground.endpoints import bp
+from auth_playground.i18n import babel
+from auth_playground.i18n import setup_i18n
+from auth_playground.oauth import bp as oauth_bp
+from auth_playground.session import ServerConfig
+
+oauth = OAuth()
+sess = Session()
+
+
+def is_oauth_configured():
+    """Check if OAuth client is configured by checking the registry."""
+    return "default" in oauth._registry
+
+
+def is_oauth_server_from_env(app):
+    """Check if OAuth server is set via environment variables."""
+    return bool(app.config.get("OAUTH_AUTH_SERVER"))
+
+
+def is_oauth_client_from_env(app):
+    """Check if OAuth client credentials are set via environment variables."""
+    return bool(app.config.get("OAUTH_CLIENT_ID"))
+
+
+def get_oauth_config(app):
+    """Get OAuth config from environment or session, with env taking priority."""
+    env_config = {
+        "client_id": app.config.get("OAUTH_CLIENT_ID"),
+        "client_secret": app.config.get("OAUTH_CLIENT_SECRET"),
+        "auth_server": app.config.get("OAUTH_AUTH_SERVER"),
+    }
+
+    session_config = {}
+    if has_request_context():
+        session_config = flask_session.get("oauth_config", {})
+    config = {
+        **session_config,
+        **{k: v for k, v in env_config.items() if v is not None},
+    }
+
+    return config
+
+
+def setup_oauth(app):
+    """Initialize OAuth client with configuration from environment or session."""
+    if "default" in oauth._registry:
+        del oauth._registry["default"]
+
+    config = get_oauth_config(app)
+    if not config:
+        return False
+
+    oauth.init_app(app)
+
+    oauth.register(
+        name="default",
+        client_id=config["client_id"],
+        client_secret=config["client_secret"],
+        server_metadata_url=get_well_known_url(config["auth_server"], external=True),
+        client_kwargs={"scope": "openid profile email phone address groups"},
+    )
+    return True
+
+
+def setup_oauth_runtime(app, client_id, client_secret, auth_server):
+    """Set up OAuth with runtime configuration stored in session."""
+    flask_session["oauth_config"] = {
+        "client_id": client_id,
+        "client_secret": client_secret,
+        "auth_server": auth_server,
+    }
+
+    return setup_oauth(app)
+
+
+def create_app():
+    """Create and configure the Flask application."""
+    app = Flask(__name__)
+
+    app.config["SECRET_KEY"] = os.environ.get(
+        "SECRET_KEY", "dev-secret-key-change-in-production"
+    )
+    app.config["NAME"] = os.environ.get("APP_NAME", "Auth Playground")
+
+    app.config["SESSION_TYPE"] = "cachelib"
+    app.config["SESSION_CACHELIB"] = SimpleCache()
+    app.config["SESSION_PERMANENT"] = False
+
+    app.config["BABEL_DEFAULT_LOCALE"] = "en"
+    app.config["BABEL_DEFAULT_TIMEZONE"] = "UTC"
+
+    oauth_auth_server_env = os.environ.get("OAUTH_AUTH_SERVER")
+    app.config["OAUTH_CLIENT_ID"] = os.environ.get("OAUTH_CLIENT_ID")
+    app.config["OAUTH_CLIENT_SECRET"] = os.environ.get("OAUTH_CLIENT_SECRET")
+    app.config["OAUTH_AUTH_SERVER"] = (
+        oauth_auth_server_env.rstrip("/") if oauth_auth_server_env else None
+    )
+
+    sess.init_app(app)
+    setup_i18n(app)
+
+    # Register OAuth blueprint without language prefix (technical endpoints)
+    app.register_blueprint(oauth_bp)
+
+    # Register main blueprint with mandatory language prefix (/<lang:lang_code>/...)
+    # The 'lang' converter validates that lang_code is an available language
+    app.register_blueprint(bp, url_prefix="/<lang:lang_code>")
+
+    @app.route("/")
+    def root():
+        """Redirect to the appropriate language prefix based on browser preference."""
+        available_langs = [locale.language for locale in babel.list_translations()]
+        default_lang = app.config.get("BABEL_DEFAULT_LOCALE", "en")
+        lang = request.accept_languages.best_match(available_langs) or default_lang
+        return redirect(url_for("routes.index", lang_code=lang))
+
+    @app.before_request
+    def load_server_config():
+        """Load server configuration into flask.g."""
+        setup_oauth(app)
+
+        if not g.get("server_config"):
+            g.server_config = ServerConfig.deserialize(flask_session)
+            if not g.server_config:
+                g.server_config = ServerConfig()
+            if issuer_url := app.config.get("OAUTH_AUTH_SERVER"):
+                g.server_config.issuer_url = issuer_url
+
+    @app.context_processor
+    def inject_server_info():
+        """Inject server information into all templates."""
+        pkg_metadata = importlib.metadata.metadata("auth-playground")
+        project_urls = dict(
+            [url.split(", ", 1) for url in pkg_metadata.get_all("Project-URL") or []]
+        )
+        return {
+            "app_version": importlib.metadata.version("auth-playground"),
+            "repository_url": project_urls.get("repository"),
+        }
+
+    return app

auth_playground/cli.py

@@ -0,0 +1,19 @@
+import os  # pragma: no cover
+
+from dotenv import load_dotenv  # pragma: no cover
+
+from auth_playground import create_app  # pragma: no cover
+
+
+def run():  # pragma: no cover
+    """Run the Auth Playground application."""
+    load_dotenv()
+    app = create_app()
+    host = os.environ.get("FLASK_RUN_HOST", "0.0.0.0")
+    port = int(os.environ.get("FLASK_RUN_PORT", "4000"))
+    debug = os.environ.get("FLASK_DEBUG", "True").lower() == "true"
+    app.run(host=host, port=port, debug=debug)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run()

auth_playground/endpoints.py

@@ -0,0 +1,284 @@
+import requests
+from flask import Blueprint
+from flask import current_app
+from flask import flash
+from flask import g
+from flask import redirect
+from flask import render_template
+from flask import session
+from flask import url_for
+from flask_babel import gettext as _
+
+import auth_playground
+from auth_playground.forms import ClientConfigForm
+from auth_playground.forms import DynamicRegistrationForm
+from auth_playground.forms import RefreshTokenForm
+from auth_playground.forms import ServerConfigForm
+from auth_playground.forms import UnregisterClientForm
+from auth_playground.oauth import clear_user_session
+from auth_playground.session import ServerConfig
+
+bp = Blueprint("routes", __name__)
+
+
+def fetch_server_metadata(issuer_url: str, timeout: int = 10) -> tuple[dict, str]:
+    """Fetch server metadata from well-known OIDC or OAuth2 endpoints."""
+    oidc_url = f"{issuer_url}/.well-known/openid-configuration"
+    try:
+        response = requests.get(oidc_url, timeout=timeout)
+        response.raise_for_status()
+        return response.json(), "oidc"
+    except requests.exceptions.HTTPError as e:
+        if e.response.status_code != 404:
+            raise  # Only try OAuth2 endpoint if OIDC endpoint is not found
+
+    oauth2_url = f"{issuer_url}/.well-known/oauth-authorization-server"
+    response = requests.get(oauth2_url, timeout=timeout)
+    response.raise_for_status()
+    return response.json(), "oauth2"
+
+
+def handle_fetch_metadata_errors(issuer_url: str, on_error):
+    """Fetch server metadata and handle errors with custom error handler."""
+    try:
+        return fetch_server_metadata(issuer_url)
+    except requests.exceptions.ConnectionError:
+        flash(_("Cannot connect to the server. Please check the URL."), "error")
+        return on_error()
+    except requests.exceptions.Timeout:
+        flash(_("Connection timeout. The server is not responding."), "error")
+        return on_error()
+    except requests.exceptions.HTTPError as e:
+        if e.response.status_code == 404:
+            flash(
+                _(
+                    "This server does not support OIDC Discovery or OAuth 2.0 Authorization Server Metadata"
+                ),
+                "error",
+            )
+        else:
+            flash(
+                _("Server returned an error: HTTP {status_code}").format(
+                    status_code=e.response.status_code
+                ),
+                "error",
+            )
+        return on_error()
+    except requests.RequestException:
+        flash(_("Failed to connect to the server. Please check the URL."), "error")
+        return on_error()
+    except ValueError:
+        flash(_("Invalid response from server"), "error")
+        return on_error()
+
+
+def clear_server_session():
+    """Clear all server-related data from the session."""
+    clear_user_session()
+    ServerConfig.clear(session)
+
+    try:
+        del session["oauth_config"]
+    except KeyError:
+        pass
+
+
+@bp.route("/")
+def index():
+    """Redirect to the appropriate configuration step or main page."""
+    server_configured = auth_playground.is_oauth_server_from_env(current_app) or (
+        g.server_config and g.server_config.issuer_url
+    )
+    client_configured = auth_playground.is_oauth_configured()
+
+    if not server_configured:
+        return redirect(url_for("routes.configure_server"))
+
+    elif not client_configured:
+        return redirect(url_for("routes.configure_client"))
+
+    return redirect(url_for("routes.playground"))
+
+
+@bp.route("/server", methods=["GET", "POST"])
+@bp.route("/server/<path:domain>", methods=["GET", "POST"])
+def configure_server(domain=None):
+    """Display form to configure and validate identity provider URL."""
+    if auth_playground.is_oauth_server_from_env(current_app):
+        flash(
+            _(
+                "OAuth configuration is set via environment variables and cannot be changed"
+            ),
+            "warning",
+        )
+        return redirect(url_for("routes.playground"))
+
+    form = ServerConfigForm()
+
+    if domain:
+        if not domain.startswith(("http://", "https://")):
+            domain = f"https://{domain}"
+        issuer_url = domain.rstrip("/")
+
+    elif not form.validate_on_submit():
+        if g.server_config and g.server_config.issuer_url:
+            flash(_("You can now configure a different identity provider"), "info")
+        clear_server_session()
+        g.server_config = ServerConfig()
+        return render_template("configure_server.html", form=form)
+
+    else:
+        issuer_url = form.issuer_url.data.rstrip("/")
+
+    result = handle_fetch_metadata_errors(
+        issuer_url, lambda: render_template("configure_server.html", form=form)
+    )
+    if not isinstance(result, tuple):
+        return result
+    metadata, server_type = result
+
+    g.server_config = ServerConfig(
+        metadata=metadata,
+        issuer_url=issuer_url,
+        server_type=server_type,
+    )
+    g.server_config.save(session)
+
+    flash(_("Server metadata successfully loaded"), "success")
+
+    return redirect(url_for("routes.configure_client"))
+
+
+@bp.route("/client", methods=["GET", "POST"])
+def configure_client():
+    """Display options to configure OAuth client credentials."""
+    if auth_playground.is_oauth_client_from_env(current_app):
+        flash(
+            _("OAuth client is set via environment variables and cannot be changed"),
+            "warning",
+        )
+        return redirect(url_for("routes.playground"))
+
+    issuer_url = g.server_config.issuer_url
+    if not issuer_url:
+        flash(_("Please configure a server"), "warning")
+        return redirect(url_for("routes.configure_server"))
+
+    if not g.server_config.metadata:
+        result = handle_fetch_metadata_errors(
+            issuer_url, lambda: redirect(url_for("routes.configure_server"))
+        )
+        if not isinstance(result, tuple):
+            return result
+        metadata, server_type = result
+        g.server_config.metadata = metadata
+        g.server_config.issuer_url = issuer_url.rstrip("/")
+        g.server_config.server_type = server_type
+        g.server_config.save(session)
+
+    client_form = ClientConfigForm()
+    dynamic_registration_form = DynamicRegistrationForm()
+
+    if not client_form.validate_on_submit():
+        return render_template(
+            "configure_client.html",
+            client_form=client_form,
+            dynamic_registration_form=dynamic_registration_form,
+        )
+
+    auth_playground.setup_oauth_runtime(
+        current_app,
+        client_form.client_id.data,
+        client_form.client_secret.data,
+        issuer_url,
+    )
+    flash(_("OAuth configuration completed successfully"), "success")
+    return redirect(url_for("routes.playground"))
+
+
+@bp.route("/playground")
+def playground():
+    """Display the main playground page with OAuth 2.0 demonstration controls."""
+    server_configured = auth_playground.is_oauth_server_from_env(current_app) or (
+        g.server_config and g.server_config.issuer_url
+    )
+    client_configured = auth_playground.is_oauth_configured()
+
+    if not server_configured:
+        return redirect(url_for("routes.configure_server"))
+
+    elif not client_configured:
+        return redirect(url_for("routes.configure_client"))
+
+    if g.server_config and not g.server_config.metadata:
+        issuer_url = current_app.config.get("OAUTH_AUTH_SERVER")
+        if issuer_url:
+            try:
+                metadata, server_type = fetch_server_metadata(issuer_url)
+                g.server_config.metadata = metadata
+                g.server_config.server_type = server_type
+                if not current_app.config.get("OAUTH_AUTH_SERVER"):
+                    g.server_config.save(session)
+            except Exception:
+                pass
+
+    refresh_form = RefreshTokenForm()
+    unregister_form = UnregisterClientForm()
+    return render_template(
+        "playground.html",
+        refresh_form=refresh_form,
+        unregister_form=unregister_form,
+    )
+
+
+@bp.route("/specs")
+def specs():
+    """Display server specifications."""
+    if not g.server_config or not g.server_config.specs:
+        flash(_("No server configured"), "warning")
+        return redirect(url_for("routes.configure_server"))
+
+    server_specs = g.server_config.specs
+    supported_specs = [
+        (
+            spec,
+            server_specs.get_spec_display_name(spec),
+            server_specs.get_spec_url(spec),
+        )
+        for spec in server_specs.get_supported_specs()
+    ]
+    unsupported_specs = [
+        (
+            spec,
+            server_specs.get_spec_display_name(spec),
+            server_specs.get_spec_url(spec),
+        )
+        for spec in server_specs.get_unsupported_specs()
+    ]
+    unknown_specs = [
+        (
+            spec,
+            server_specs.get_spec_display_name(spec),
+            server_specs.get_spec_url(spec),
+        )
+        for spec in server_specs.get_unknown_specs()
+    ]
+
+    return render_template(
+        "specs.html",
+        supported_specs=supported_specs,
+        unsupported_specs=unsupported_specs,
+        unknown_specs=unknown_specs,
+    )
+
+
+@bp.route("/tos")
+def tos():
+    """Display the Terms of Service page."""
+    return render_template("tos.html")
+
+
+@bp.route("/policy")
+def policy():
+    """Display the Privacy Policy page."""
+    return render_template("policy.html")

auth_playground/forms.py

@@ -0,0 +1,91 @@
+from flask import current_app
+from flask_babel import lazy_gettext as _
+from flask_wtf import FlaskForm
+from wtforms import PasswordField
+from wtforms import StringField
+from wtforms import SubmitField
+from wtforms import ValidationError
+from wtforms.validators import DataRequired
+from wtforms.validators import Length
+
+
+class RefreshTokenForm(FlaskForm):
+    """Form to refresh access token using refresh token."""
+
+    submit = SubmitField(_("Renew tokens"))
+
+
+def validate_issuer_url(form, field):
+    """Validate issuer URL with relaxed rules in debug/testing mode."""
+    url = field.data
+
+    if not url.startswith(("http://", "https://")):
+        raise ValidationError(_("URL must start with http:// or https://"))
+
+    is_debug = current_app.debug
+    is_testing = current_app.testing
+
+    if url.startswith("http://") and not (is_debug or is_testing):  # pragma: no cover
+        raise ValidationError(
+            _("HTTP is only allowed in debug or testing mode. Use HTTPS in production.")
+        )
+
+
+class ServerConfigForm(FlaskForm):
+    """Form to configure the provider server URL."""
+
+    issuer_url = StringField(
+        _("Provider URL:"),
+        validators=[
+            DataRequired(message=_("Provider URL is required")),
+            validate_issuer_url,
+        ],
+        description=_(
+            "Enter the base URL of your OIDC/OAuth2 provider (e.g., https://auth.example.com)"
+        ),
+        render_kw={"placeholder": "https://auth.example.com", "type": "url"},
+    )
+    submit = SubmitField(_("Continue"))
+
+
+class ClientConfigForm(FlaskForm):
+    """Form to configure OAuth client credentials manually."""
+
+    client_id = StringField(
+        _("Client ID:"),
+        validators=[
+            DataRequired(message=_("Client ID is required")),
+            Length(
+                min=1,
+                max=255,
+                message=_("Client ID must be between 1 and 255 characters"),
+            ),
+        ],
+        render_kw={"placeholder": "auth-playground-client"},
+    )
+    client_secret = PasswordField(
+        _("Client secret:"),
+        validators=[
+            DataRequired(message=_("Client Secret is required")),
+            Length(min=1, message=_("Client Secret is required")),
+        ],
+        render_kw={"placeholder": "******************"},
+    )
+    submit = SubmitField(_("Complete configuration"))
+
+
+class DynamicRegistrationForm(FlaskForm):
+    """Form to trigger dynamic client registration with CSRF protection."""
+
+    initial_access_token = StringField(
+        _("Initial access token:"),
+        validators=[],
+        render_kw={"placeholder": _("Leave empty if not required")},
+    )
+    submit = SubmitField(_("Register client"))
+
+
+class UnregisterClientForm(FlaskForm):
+    """Form to trigger client unregistration with CSRF protection."""
+
+    submit = SubmitField(_("Unregister client"))

auth_playground/i18n.py

@@ -0,0 +1,76 @@
+from flask import g
+from flask_babel import Babel
+from flask_babel import get_locale
+from werkzeug.exceptions import NotFound
+from werkzeug.routing import BaseConverter
+
+babel = Babel()
+
+
+class LangConverter(BaseConverter):
+    """URL converter that validates language codes against available translations."""
+
+    def __init__(self, map, *args, **kwargs):
+        super().__init__(map, *args, **kwargs)
+        self.regex = r"[a-z]{2,3}"
+
+    def to_python(self, value):
+        """Convert URL value to Python, validating against available translations.
+
+        Raises 404 if language code is not available.
+        """
+        available_langs = [locale.language for locale in babel.list_translations()]
+
+        if value not in available_langs:
+            raise NotFound(
+                f"Language '{value}' is not available. "
+                f"Available languages: {', '.join(available_langs)}"
+            )
+
+        return value
+
+    def to_url(self, value):
+        """Convert Python value to URL."""
+        return value
+
+
+def setup_i18n(app):
+    @app.url_defaults
+    def add_language_code(endpoint, values):
+        """Automatically inject language code into url_for() calls when using i18n routes."""
+        if endpoint and endpoint.startswith("oauth."):
+            return
+
+        if not g.get("lang_code"):
+            g.lang_code = app.config.get("BABEL_DEFAULT_LOCALE", "en")
+
+        if "lang_code" not in values:
+            values.setdefault("lang_code", g.lang_code)
+
+    @app.url_value_preprocessor
+    def pull_lang_code(endpoint, values):
+        """Extract language code from URL and store in g.lang_code for i18n routes."""
+        if values is not None and "lang_code" in values:
+            g.lang_code = values.pop("lang_code")
+
+    @app.before_request
+    def before_request():
+        g.available_languages = babel.list_translations()
+        g.available_language_codes = [
+            locale.language for locale in g.available_languages
+        ]
+
+    @app.context_processor
+    def global_processor():
+        return {
+            "locale": get_locale(),
+            "available_languages": getattr(g, "available_languages", []),
+        }
+
+    def locale_selector():
+        # Language is always specified in URL prefix (mandatory)
+        return g.get("lang_code", app.config["BABEL_DEFAULT_LOCALE"])
+
+    babel.init_app(app, locale_selector=locale_selector)
+    app.url_map.converters["lang"] = LangConverter
+    app.jinja_env.policies["ext.i18n.trimmed"] = True