charmlibs-interfaces-oauth 1.0.0__tar.gz

charmlibs_interfaces_oauth-1.0.0/.gitignore

@@ -0,0 +1,187 @@
+# 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
+cos-tool*
+# 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.*
+.coverage-*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.report/
+
+# 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
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.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/
+
+# PyPI configuration file
+.pypirc
+
+# packed charms
+.packed
+
+# temporary directory for packing charms
+.tmp
+
+# uv.lock from example libraries as we don't commit these
+.example/**/uv.lock
+.tutorial/**/uv.lock
+interfaces/.example/**/uv.lock
+
+# Workshop lock file (machine-local state)
+.workshop.lock

charmlibs_interfaces_oauth-1.0.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+Initial release. Migrated from `charms.hydra.v0.oauth` (v0.12).

charmlibs_interfaces_oauth-1.0.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: charmlibs-interfaces-oauth
+Version: 1.0.0
+Summary: The charmlibs.interfaces.oauth package.
+Project-URL: Documentation, https://canonical.com/juju/docs/charmlibs/reference/charmlibs/interfaces/oauth
+Project-URL: Repository, https://github.com/canonical/charmlibs/tree/main/interfaces/oauth
+Project-URL: Issues, https://github.com/canonical/charmlibs/issues
+Project-URL: Changelog, https://github.com/canonical/charmlibs/blob/main/interfaces/oauth/CHANGELOG.md
+Author: Identity Team at Canonical
+License-Expression: Apache-2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: ops<4,>=2.23.1
+Description-Content-Type: text/markdown
+
+# charmlibs.interfaces.oauth
+
+The `oauth` interface library.
+
+To install, add `charmlibs-interfaces-oauth` to your Python dependencies. Then in your Python code, import as:
+
+```py
+from charmlibs.interfaces import oauth
+```
+
+See the [reference documentation](https://canonical.com/juju/docs/charmlibs/reference/charmlibs/interfaces/oauth) for more.

charmlibs_interfaces_oauth-1.0.0/README.md

@@ -0,0 +1,11 @@
+# charmlibs.interfaces.oauth
+
+The `oauth` interface library.
+
+To install, add `charmlibs-interfaces-oauth` to your Python dependencies. Then in your Python code, import as:
+
+```py
+from charmlibs.interfaces import oauth
+```
+
+See the [reference documentation](https://canonical.com/juju/docs/charmlibs/reference/charmlibs/interfaces/oauth) for more.

charmlibs_interfaces_oauth-1.0.0/interface/v0/README.md

@@ -0,0 +1,85 @@
+# `oauth/v0`
+
+## Overview
+
+This relation interface describes the expected behavior of any charm claiming to be able to interface with an OAuth2/OIDC Provider.
+
+## Usage
+
+Charms claiming to provide this interface must implement the OAuth2/OIDC protocol and register a client for each relation. In most cases, this will be accomplished using the [oauth](https://charmhub.io/hydra/libraries/oauth) library, although charm developers are free to provide alternative libraries as long as they fulfill the behavioral and schematic requirements described in this document.
+
+## Direction
+
+The `oauth` interface implements a provider/requirer pattern.
+The requirer is a charm that wishes to act as a oauth2 client, and the provider is a charm exposing an OAuth2/OIDC provider.
+
+```mermaid
+flowchart TD
+    Requirer -- redirect_uri, audience, scope, grant_types, token_endpoint_auth_method --> Provider
+    Provider -- issuer_url, authentication_endpoint, token_endpoint, userinfo_endpoint, introspection_endpoint, jwks_endpoint, client_id, client_secret_id, scope, groups --> Requirer
+```
+
+## Behavior
+
+The requirer and the provider must adhere to a certain set of criteria to be considered compatible with the interface.
+
+### Provider
+
+- Is expected to provide its endpoints (`authentication_endpoint`, `token_endpoint`, `userinfo_endpoint`, `introspection_endpoint` and `jwks_endpoint`) in the relation databag.
+- Is expected to provide the `issuer_url` in the relation databag.
+- Is expected to provide the supported scopes in the databag.
+- Is expected to register a client and provide the `client_id` in the databag.
+- Is expected to register a client, place the `client_secret` in a juju secret and provide the juju secret ID in the databag (`client_secret_id`).
+- Is expected to provide the groups claim, if one is available.
+
+As mentioned above the field `client_secret_id` holds the id of a Juju Secret, this means that the charms implementing the relation must be running on Juju >3 in order be able to use Juju secrets.
+
+### Requirer
+
+- Is expected to provide a user accessible `redirect_uri` using the HTTPS scheme.
+- Is expected to provide an audience for the issued tokens, if extra audience are required.
+- Is expected to provide the `grant_types` and `token_endpoint_auth_method` it wishes to use.
+- Is expected to provide the scopes that should be allowed for this client.
+
+## Relation Data
+
+### Provider
+
+[\[JSON Schema\]](./schemas/provider.json)
+
+Provider provides its endpoints, configurations and the client credentials. It should be placed in the **application** databag.
+
+#### Example
+
+```yaml
+related-units: {}
+application_data: {
+  "issuer_url": "https://auth_server_public_url/",
+  "authorization_endpoint": "https://auth_server_public_url/authorize",
+  "token_endpoint": "https://auth_server_public_url/token",
+  "introspection_endpoint": "https://auth_server_public_url/introspect",
+  "userinfo_endpoint": "https://auth_server_public_url/userinfo",
+  "jwks_endpoint": "https://auth_server_public_url/jwks",
+  "scope": "openid profile email phone",
+  "client_id": "some_id",
+  "client_secret_id": "42174217421742",
+}
+```
+
+### Requirer
+
+[\[JSON Schema\]](./schemas/requirer.json)
+
+Requirer requires its client configurations. It should be placed in the **application** databag.
+
+#### Example
+```yaml
+related-units: {}
+application-data: {
+  "redirect_uri": "https://some_url/callback",
+  "audience": [],
+  "scope": "openid email",
+  "grant_types": ["authorization_code"],
+  "token_endpoint_auth_method": "client_secret_basic"
+}
+```

charmlibs_interfaces_oauth-1.0.0/interface/v0/interface.yaml

@@ -0,0 +1,18 @@
+name: oauth
+version: 0
+status: draft
+lib: charmlibs.interfaces.oauth
+summary: Connect to an OAuth2/OIDC Provider.
+description: |
+  The `oauth` interface allows charms to interface with an OAuth2/OIDC Provider.
+  The requirer acts as an OAuth2 client.
+  The provider exposes an OAuth2/OIDC Provider.
+
+providers:
+  - name: hydra-operator
+    url: https://www.github.com/canonical/hydra-operator
+
+requirers:
+  []
+
+maintainer: identity

charmlibs_interfaces_oauth-1.0.0/interface/v0/schemas/provider.json

@@ -0,0 +1,122 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema",
+    "$id": "https://canonical.github.io/charm-relation-interfaces/interfaces/oauth/schemas/provider.json",
+    "type": "object",
+    "title": "`oauth` provider schema",
+    "description": "The `oauth` root schema comprises the entire provider databag for this interface.",
+    "default": {},
+    "examples": [
+        {
+            "application-data": {
+                "issuer_url": "https://auth_server_public_url/",
+                "authorization_endpoint": "https://auth_server_public_url/authorize",
+                "token_endpoint": "https://auth_server_public_url/token",
+                "introspection_endpoint": "https://auth_server_public_url/introspect",
+                "userinfo_endpoint": "https://auth_server_public_url/userinfo",
+                "jwks_endpoint": "https://auth_server_public_url/jwks",
+                "scope": "openid profile email phone",
+                "client_id": "some_id",
+                "client_secret_id": "42174217421742"
+            },
+            "related-units": {}
+        }
+    ],
+    "properties": {
+        "application-data": {
+            "$id": "#/properties/application-data",
+            "title": "Application Databag",
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+                "issuer_url": {
+                    "type": "string",
+                    "title": "Issuer URL",
+                    "description": "The OpenID Connect identity provider's issuer URL.",
+                    "examples": [
+                        "https://some_url/"
+                    ]
+                },
+                "authorization_endpoint": {
+                    "type": "string",
+                    "title": "Authorization Endpoint",
+                    "description": "The OpenID Connect identity provider's authorization endpoint URL.",
+                    "examples": [
+                        "https://some_url/authorize"
+                    ]
+                },
+                "token_endpoint": {
+                    "type": "string",
+                    "title": "Token Endpoint",
+                    "description": "The OpenID Connect identity provider's token endpoint URL.",
+                    "examples": [
+                        "https://some_url/token"
+                    ]
+                },
+                "introspection_endpoint": {
+                    "type": "string",
+                    "title": "Introspection Endpoint",
+                    "description": "The OpenID Connect identity provider's introspection endpoint URL.",
+                    "examples": [
+                        "https://some_url/introspect"
+                    ]
+                },
+                "userinfo_endpoint": {
+                    "type": "string",
+                    "title": "Userinfo Endpoint",
+                    "description": "The OpenID Connect identity provider's Userinfo Userinfo URL.",
+                    "examples": [
+                        "https://some_url/userinfo"
+                    ]
+                },
+                "jwks_endpoint": {
+                    "type": "string",
+                    "title": "JWKS Endpoint",
+                    "description": "The OpenID Connect identity provider's jwks endpoint URL.",
+                    "examples": [
+                        "https://some_url/jwks"
+                    ]
+                },
+                "scope": {
+                    "type": "string",
+                    "title": "Scope",
+                    "description": "A space-separated list with the OpenID Connect identity provider's supported scopes."
+                },
+                "client_id": {
+                    "type": "string",
+                    "title": "Client ID",
+                    "description": "The client_id."
+                },
+                "client_secret_id": {
+                    "type": "string",
+                    "title": "Juju secret ID",
+                    "description": "The juju secret ID that holds the client_secret."
+                },
+                "groups": {
+                    "type": "string",
+                    "title": "Groups Claim Name",
+                    "description": "The name of the claim that represents the user's groups",
+                    "default": null
+                }
+            },
+            "required": [
+                "issuer_url",
+                "authorization_endpoint",
+                "token_endpoint",
+                "introspection_endpoint",
+                "userinfo_endpoint",
+                "jwks_endpoint",
+                "scope",
+                "client_id"
+            ]
+        },
+        "related-units": {
+            "type": "object",
+            "patternProperties": {
+                "^.*/d+$": {
+                    "type": "object",
+                    "additionalProperties": true
+                }
+            }
+        }
+    }
+}

charmlibs_interfaces_oauth-1.0.0/interface/v0/schemas/requirer.json

@@ -0,0 +1,91 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema",
+    "$id": "https://canonical.github.io/charm-relation-interfaces/interfaces/oauth/schemas/requirer.json",
+    "type": "object",
+    "title": "`oauth` requirer schema",
+    "description": "The `oauth` root schema comprises the entire requirer databag for this interface.",
+    "default": {},
+    "examples": [
+        {
+            "application-data": {
+                "redirect_uri": "https://some_url/callback",
+                "audience": [],
+                "scope": "openid email",
+                "grant_types": ["authorization_code"],
+                "token_endpoint_auth_method": ["client_secret_basic"]
+            },
+            "related-units": {}
+        }
+    ],
+    "properties": {
+        "application-data": {
+            "$id": "#/properties/application-data",
+            "title": "Application Databag",
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+                "redirect_uri": {
+                    "type": "string",
+                    "title": "Redirect URI",
+                    "description": "The client's redirect_uri, must be using the HTTPS scheme.",
+                    "default": null,
+                    "examples": [
+                        "https://some_url/callback"
+                    ]
+                    },
+                "audience": {
+                    "type": "array",
+                    "title": "Audience",
+                    "description": "List of audience the client will be allowed to request.",
+                    "default": [],
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "scope": {
+                    "type": "string",
+                    "title": "Scope",
+                    "description": "The scopes the client wishes to use, must be a space-separated subset of the Provider's allowed scope.",
+                    "default": null
+                },
+                "grant_types": {
+                    "type": "array",
+                    "title": "Grant Types",
+                    "description": "The grant types the client wishes to use, must be a subset of the Provider's allowed grant types.",
+                    "default": null,
+                    "items": {
+                        "enum": ["authorization_code", "client_credentials", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code"],
+                        "type": "string"
+                    }
+                },
+                "token_endpoint_auth_method": {
+                    "type": "string",
+                    "enum": ["client_secret_basic", "client_secret_post"],
+                    "title": "Token Endpoint Client Authentication Methods",
+                    "description": "The client authentication methods the clients wishes to use, it must be a subset of the supported client authentication methods of the Provider.",
+                    "default": "client_secret_basic"
+                }
+            },
+            "required": [
+                "redirect_uri",
+                "audience",
+                "scope",
+                "grant_types",
+                "token_endpoint_auth_method"
+            ]
+            },
+            "related-units": {
+                "type": "object",
+                "patternProperties": {
+                    "^.*/d+$": {
+                        "type": "object",
+                        "additionalProperties": true
+                    }
+                }
+            }
+        },
+        "required": [
+            "application-data",
+            "related-units"
+        ]
+}

charmlibs_interfaces_oauth-1.0.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "charmlibs-interfaces-oauth"
+description = "The charmlibs.interfaces.oauth package."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name="Identity Team at Canonical"},
+]
+license = "Apache-2.0"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Development Status :: 5 - Production/Stable",
+]
+dynamic = ["version"]
+dependencies = [
+    # Libraries should use clear but wide dependency bounds to avoid overly constraining charms.
+    # Ops 3 is backwards compatible with Ops 2, but drops Python 3.8 support.
+    # Ops 3 has new features not present in Ops 2.23 (the last Ops 2 feature release).
+    # See the Ops 2.23 maintenance branch changelog and the Ops 3 changelog for current information:
+    # - https://github.com/canonical/operator/blob/2.23-maintenance/CHANGES.md
+    # - https://github.com/canonical/operator/blob/main/CHANGES.md
+    # Set the dependency bounds according to the features and fixes your library needs.
+    "jsonschema>=4.26.0",
+    "ops>=2.23.1,<4",
+]
+
+
+[dependency-groups]
+lint = [  # installed for `just lint interfaces/oauth` (unit, functional, and integration are also installed)
+    # "typing_extensions",
+]
+unit = [  # installed for `just unit interfaces/oauth`
+    "ops[testing]",
+]
+functional = [  # installed for `just functional interfaces/oauth`
+]
+integration = [  # installed for `just integration interfaces/oauth`
+    "jubilant",
+]
+
+[project.urls]
+"Documentation" = "https://canonical.com/juju/docs/charmlibs/reference/charmlibs/interfaces/oauth"
+"Repository" = "https://github.com/canonical/charmlibs/tree/main/interfaces/oauth"
+"Issues" = "https://github.com/canonical/charmlibs/issues"
+"Changelog" = "https://github.com/canonical/charmlibs/blob/main/interfaces/oauth/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/charmlibs"]
+
+[tool.hatch.version]
+path = "src/charmlibs/interfaces/oauth/_version.py"
+
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+src = ["src", "tests/unit", "tests/functional", "tests/integration"]  # correctly sort local imports in tests
+
+[tool.ruff.lint.extend-per-file-ignores]
+# add additional per-file-ignores here to avoid overriding repo-level config
+"tests/**/*" = [
+    # "E501",  # line too long
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["src", "tests"]
+pythonVersion = "3.10"  # check no python > 3.10 features are used
+
+[tool.charmlibs.functional]
+ubuntu = []  # ubuntu versions to run functional tests with, e.g. "24.04" (defaults to just "latest")
+pebble = []  # pebble versions to run functional tests with, e.g. "v1.0.0", "master" (defaults to no pebble versions)
+sudo = false  # whether to run functional tests with sudo (defaults to false)
+
+[tool.charmlibs.integration]
+# tags to run integration tests with (defaults to running once with no tag, i.e. tags = [''])
+# Available in CI in tests/integration/pack.sh and integration tests as CHARMLIBS_TAG
+tags = []  # Not used by the pack.sh and integration tests generated by the template