obi-auth 0.0.1__tar.gz

obi_auth-0.0.1/.github/workflows/sdist.yml

@@ -0,0 +1,48 @@
+name: PyPI
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+     - main
+  release:
+    types:
+      - published
+
+jobs:
+
+  build_sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build SDist
+        run: pipx run build --sdist
+
+      - name: Check metadata
+        run: pipx run twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build
+          path: dist
+
+  upload_sdist:
+    name: Upload sdist
+    needs: [build_sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    if: github.event_name == 'release' && github.event.action == 'published'
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: build
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

obi_auth-0.0.1/.github/workflows/tox.yml

@@ -0,0 +1,49 @@
+name: Run tox
+
+on:
+  pull_request:
+  push:
+    branches:
+    - main
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+        - python-version: '3.11'
+          tox-env: py311
+        - python-version: '3.11'
+          tox-env: lint
+        - python-version: '3.12'
+          tox-env: py312
+        - python-version: '3.13'
+          tox-env: py313
+          codecov: codecov
+        - python-version: '3.13'
+          tox-env: check-packaging
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        python -m pip install --upgrade tox tox-uv
+    - name: Run tox
+      run: |
+        tox run -e ${{ matrix.tox-env }}
+    - name: Upload to codecov
+      if: ${{ matrix.codecov == 'codecov' }}
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        fail_ci_if_error: false
+        files: ./coverage.xml
+        flags: pytest
+        verbose: true
+        name: "${{ github.repository }}-${{ matrix.tox-env }}"

obi_auth-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+*.pyc
+*.swp
+coverage.xml
+*.egg-info
+.coverage*
+.tox
+build
+dist
+venv
+.eggs
+.idea
+__pycache__
+htmlcov

obi_auth-0.0.1/CHANGELOG.rst

@@ -0,0 +1,21 @@
+Changelog
+=========
+
+Version 0.1
+-----------
+
+New Features
+~~~~~~~~~~~~
+- Example code in Python
+
+
+Bug Fixes
+~~~~~~~~~
+- Describe Bug Fixes here
+- Remove this subsection if there are no Bug Fixes
+
+
+Improvements
+~~~~~~~~~~~~
+- Describe Improvements here
+- Remove this subsection if there are no Improvements

obi_auth-0.0.1/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

obi_auth-0.0.1/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: obi_auth
+Version: 0.0.1
+Summary: Python library for retrieving Keycloak access tokens interactively
+Author-email: Open Brain Institute <info@openbraininstitute.org>
+Maintainer-email: Open Brain Institute <info@openbraininstitute.org>
+License: Apache-2.0
+Project-URL: documentation, https://github.com/openbraininstitute/obi-auth
+Project-URL: repository, https://github.com/openbraininstitute/obi-auth
+Project-URL: changelog, https://github.com/openbraininstitute/obi-auth/CHANGELOG.rst
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Dist: pydantic-settings
+Requires-Dist: uvicorn
+Requires-Dist: fastapi
+Dynamic: license-file
+
+[![Build status][build_status_badge]][build_status_target]
+[![License][license_badge]][license_target]
+[![Code coverage][coverage_badge]][coverage_target]
+[![CodeQL][codeql_badge]][codeql_target]
+[![PyPI][pypi_badge]][pypi_target]
+
+# obi-auth
+
+obi-auth is a library for retrieving Keycloak access tokens interactively. It helps developers and testers quickly authenticate against Keycloak without writing scripts or configuring complex clients.
+
+
+## Installation
+
+```sh
+pip install obi-auth
+```
+
+## Examples
+
+```python
+from obi_auth import get_token
+
+access_token = get_token(environment="staging")
+```
+
+## License
+
+Copyright (c) 2025 Open Brain Institute
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+[build_status_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/tox.yml/badge.svg
+[build_status_target]: https://github.com/openbraininstitute/obi-auth/actions
+[license_badge]: https://img.shields.io/pypi/l/obi-auth
+[license_target]: https://github.com/openbraininstitute/obi-auth/blob/main/LICENSE.txt
+[coverage_badge]: https://codecov.io/github/openbraininstitute/obi-auth/coverage.svg?branch=main
+[coverage_target]: https://codecov.io/github/openbraininstitute/obi-auth?branch=main
+[codeql_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/github-code-scanning/codeql/badge.svg
+[codeql_target]: https://github.com/openbraininstitute/obi-auth/actions/workflows/github-code-scanning/codeql
+[pypi_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/sdist.yml/badge.svg
+[pypi_target]: https://pypi.org/project/obi-auth/
+

obi_auth-0.0.1/README.md

@@ -0,0 +1,52 @@
+[![Build status][build_status_badge]][build_status_target]
+[![License][license_badge]][license_target]
+[![Code coverage][coverage_badge]][coverage_target]
+[![CodeQL][codeql_badge]][codeql_target]
+[![PyPI][pypi_badge]][pypi_target]
+
+# obi-auth
+
+obi-auth is a library for retrieving Keycloak access tokens interactively. It helps developers and testers quickly authenticate against Keycloak without writing scripts or configuring complex clients.
+
+
+## Installation
+
+```sh
+pip install obi-auth
+```
+
+## Examples
+
+```python
+from obi_auth import get_token
+
+access_token = get_token(environment="staging")
+```
+
+## License
+
+Copyright (c) 2025 Open Brain Institute
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+[build_status_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/tox.yml/badge.svg
+[build_status_target]: https://github.com/openbraininstitute/obi-auth/actions
+[license_badge]: https://img.shields.io/pypi/l/obi-auth
+[license_target]: https://github.com/openbraininstitute/obi-auth/blob/main/LICENSE.txt
+[coverage_badge]: https://codecov.io/github/openbraininstitute/obi-auth/coverage.svg?branch=main
+[coverage_target]: https://codecov.io/github/openbraininstitute/obi-auth?branch=main
+[codeql_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/github-code-scanning/codeql/badge.svg
+[codeql_target]: https://github.com/openbraininstitute/obi-auth/actions/workflows/github-code-scanning/codeql
+[pypi_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/sdist.yml/badge.svg
+[pypi_target]: https://pypi.org/project/obi-auth/
+

obi_auth-0.0.1/pyproject.toml

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["setuptools>=42", "setuptools-scm[toml]>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "obi_auth"
+dependencies = [
+    "httpx",
+    "pydantic",
+    "pydantic-settings",
+    "uvicorn",
+    "fastapi"
+]
+authors = [
+    {name = "Open Brain Institute", email = "info@openbraininstitute.org"}
+]
+maintainers = [
+    {name = "Open Brain Institute", email = "info@openbraininstitute.org"}
+]
+description = "Python library for retrieving Keycloak access tokens interactively"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dynamic = ["version"]
+
+[project.urls]
+documentation = "https://github.com/openbraininstitute/obi-auth"
+repository = "https://github.com/openbraininstitute/obi-auth"
+changelog = "https://github.com/openbraininstitute/obi-auth/CHANGELOG.rst"
+
+[tool.setuptools_scm]
+local_scheme = "no-local-version"
+
+[tool.pytest.ini_options]
+addopts = [
+    "-vv",
+    "-ra",
+    "--import-mode=importlib",
+    "--cov=obi_auth",
+    "--durations=10",
+    "--durations-min=1.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "A", # flake8-builtins
+    "B", # bugbear
+    "D", # pydocstyle
+    "E", # pycodestyle
+    "F", # pyflakes
+    "I", # isort
+    "S", # bandit
+    "UP", # pyupgrade
+]
+ignore = [
+    "S107", "S602", "S603", "S608"
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "ANN",     # Missing type annotation
+    "D",       # pydocstyle
+    "ERA001",  # Found commented-out code
+    "INP001",  # Missing `__init__.py`
+    "PLC2701", # Private name import from external module
+    "PLR2004", # magic value (constant) used in comparison (i.e. expected == 3)
+    "S101",    # Use of `assert` detected
+    "SIM117",  # Use a single `with` statement with multiple contexts
+    "SLF001",  # private member access
+]
+
+[tool.ruff.lint.pylint]
+# Maximum number of arguments for function / method
+max-args = 12
+# Maximum number of locals for function / method body
+max-locals = 15
+# Maximum number of return / yield for function / method body
+max-returns = 6
+# Maximum number of branch for function / method body
+max-branches = 12
+# Maximum number of statements in function / method body
+max-statements = 50
+# Maximum number of public methods for a class (see R0904).
+max-public-methods = 60
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+docstring-code-format = true
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+docstring-code-line-length = 100
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+[tool.coverage.paths]
+source = [
+    "src",
+    "*/site-packages",
+]
+
+[tool.coverage.run]
+branch = true
+parallel = false
+
+[tool.coverage.report]
+show_missing = true
+precision = 0
+fail_under = 50
+
+[tool.mypy]
+show_error_codes = true
+ignore_missing_imports = true
+allow_redefinition = true

obi_auth-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

obi_auth-0.0.1/src/obi_auth/__init__.py

@@ -0,0 +1,5 @@
+"""obi_auth."""
+
+from obi_auth.client import get_token
+
+__all__ = ["get_token"]

obi_auth-0.0.1/src/obi_auth/client.py

@@ -0,0 +1,23 @@
+"""This module provides a client for the obi_auth service."""
+
+import logging
+
+from obi_auth.exception import AuthFlowError, ClientError, ConfigError, LocalServerError
+from obi_auth.flow import pkce_authenticate
+from obi_auth.server import AuthServer
+from obi_auth.typedef import DeploymentEnvironment
+
+L = logging.getLogger(__name__)
+
+
+def get_token(*, environment: DeploymentEnvironment | None = None) -> str | None:
+    """Get token."""
+    try:
+        with AuthServer().run() as local_server:
+            return pkce_authenticate(server=local_server, override_env=environment)
+    except AuthFlowError as e:
+        raise ClientError("Authentication process failed.") from e
+    except LocalServerError as e:
+        raise ClientError("Local server failed to authenticate.") from e
+    except ConfigError as e:
+        raise ClientError("There is a mistake with configuration settings.") from e

obi_auth-0.0.1/src/obi_auth/config.py

@@ -0,0 +1,45 @@
+"""This module provides a config for the obi_auth service."""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from obi_auth.exception import ConfigError
+from obi_auth.typedef import DeploymentEnvironment, KeycloakRealm
+
+
+class Settings(BaseSettings):
+    """Environment settings for this library."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="OBI_AUTH_",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+    )
+
+    KEYCLOAK_ENV: DeploymentEnvironment = DeploymentEnvironment.staging
+    KEYCLOAK_REALM: KeycloakRealm = KeycloakRealm.sbo
+    KEYCLOAK_CLIENT_ID: str = "obi-entitysdk-auth"
+
+    LOCAL_SERVER_TIMEOUT: int = 60
+
+    def get_keycloak_url(self, override_env: DeploymentEnvironment | None = None):
+        """Return keycloak url."""
+        match env := override_env or self.KEYCLOAK_ENV:
+            case DeploymentEnvironment.staging:
+                return f"https://staging.openbraininstitute.org/auth/realms/{self.KEYCLOAK_REALM}"
+            case DeploymentEnvironment.production:
+                return f"https://openbraininstitute.org/auth/realms/{self.KEYCLOAK_REALM}"
+        raise ConfigError(f"Unknown deployment environment {env}")
+
+    def get_keycloak_token_endpoint(self, override_env: DeploymentEnvironment | None = None) -> str:
+        """Return keycloak token endpoint."""
+        base_url = self.get_keycloak_url(override_env=override_env)
+        return f"{base_url}/protocol/openid-connect/token"
+
+    def get_keycloak_auth_endpoint(self, override_env: DeploymentEnvironment | None = None) -> str:
+        """Return keycloak auth endpoint."""
+        base_url = self.get_keycloak_url(override_env=override_env)
+        return f"{base_url}/protocol/openid-connect/auth"
+
+
+settings = Settings()

obi_auth-0.0.1/src/obi_auth/exception.py

@@ -0,0 +1,21 @@
+"""Exceptions module."""
+
+
+class ObiAuthError(Exception):
+    """Generic obi-auth error."""
+
+
+class AuthFlowError(ObiAuthError):
+    """Authenticatin flow error."""
+
+
+class ClientError(ObiAuthError):
+    """Client related error."""
+
+
+class LocalServerError(ObiAuthError):
+    """Local server related error."""
+
+
+class ConfigError(ObiAuthError):
+    """Configuration settings error."""

obi_auth-0.0.1/src/obi_auth/flow.py

@@ -0,0 +1,89 @@
+"""Authorization flow module."""
+
+import base64
+import hashlib
+import logging
+import os
+import re
+import urllib.parse
+import webbrowser
+
+import httpx
+
+from obi_auth.config import settings
+from obi_auth.server import AuthServer
+from obi_auth.typedef import DeploymentEnvironment
+
+L = logging.getLogger(__name__)
+
+
+def _generate_pkce_pair() -> tuple[str, str]:
+    """Generate PKCE pair."""
+    code_verifier = base64.urlsafe_b64encode(os.urandom(40)).decode("utf-8")
+    code_verifier = re.sub("[^a-zA-Z0-9]+", "", code_verifier)
+
+    code_challenge = hashlib.sha256(code_verifier.encode("utf-8")).digest()
+    code_challenge = base64.urlsafe_b64encode(code_challenge).decode("utf-8")
+    code_challenge = code_challenge.replace("=", "")
+    return code_verifier, code_challenge
+
+
+def _build_auth_url(
+    code_challenge: str, redirect_uri: str, override_env: DeploymentEnvironment | None
+) -> str:
+    """Construct authentication url to open with a browser."""
+    params = {
+        "response_type": "code",
+        "client_id": settings.KEYCLOAK_CLIENT_ID,
+        "redirect_uri": redirect_uri,
+        "scope": "openid",
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+        "kc_idp_hint": "github",
+    }
+
+    base_auth_url = settings.get_keycloak_auth_endpoint(override_env=override_env)
+
+    # Build the full URL
+    encoded_params = urllib.parse.urlencode(params)
+    return f"{base_auth_url}?{encoded_params}"
+
+
+def _authorize(
+    server: AuthServer, code_challenge: str, override_env: DeploymentEnvironment | None
+) -> str:
+    """Ask user to login in order to retrieve a code to exchange for a token."""
+    auth_url = _build_auth_url(code_challenge, server.redirect_uri, override_env)
+    L.info("Authentication url: %s", auth_url)
+    webbrowser.open(auth_url)
+    return server.wait_for_code()
+
+
+def _exchange_code_for_token(
+    code: str, redirect_uri: str, code_verifier: str, override_env: DeploymentEnvironment | None
+) -> str:
+    response = httpx.post(
+        url=settings.get_keycloak_token_endpoint(override_env=override_env),
+        data={
+            "grant_type": "authorization_code",
+            "code": code,
+            "client_id": settings.KEYCLOAK_CLIENT_ID,
+            "redirect_uri": redirect_uri,
+            "code_verifier": code_verifier,
+        },
+    )
+    response.raise_for_status()
+
+    access_token = response.json()["access_token"]
+
+    return access_token
+
+
+def pkce_authenticate(
+    *, server: AuthServer, override_env: DeploymentEnvironment | None = None
+) -> str:
+    """Get access token using the PCKE authentication flow."""
+    code_verifier, code_challenge = _generate_pkce_pair()
+    code = _authorize(server, code_challenge, override_env)
+    access_token = _exchange_code_for_token(code, server.redirect_uri, code_verifier, override_env)
+    return access_token

obi_auth-0.0.1/src/obi_auth/server.py

@@ -0,0 +1,86 @@
+"""This module provides a simple HTTP server that listens for a Keycloak authorization code."""
+
+import contextlib
+import logging
+import socket
+import threading
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Self
+
+import uvicorn
+from fastapi import FastAPI, HTTPException, Request
+
+from obi_auth.config import settings
+from obi_auth.exception import LocalServerError
+
+L = logging.getLogger(__name__)
+HOST = "localhost"
+
+
+@dataclass
+class AuthState:
+    """Class to manage authentication state."""
+
+    code: str | None = None
+    event: threading.Event = threading.Event()
+
+
+class AuthServer:
+    """Class to manage authentication state."""
+
+    def __init__(self):
+        """Initialize authentication server."""
+        self.app = FastAPI()
+        self.auth_state = AuthState()
+        self.port = None
+
+        @self.app.get("/callback")
+        def callback(request: Request):
+            """Handle the Keycloak redirect and extracts the authorization code."""
+            code = request.query_params.get("code")
+
+            if not code:
+                raise HTTPException(status_code=400, detail="Authorization code not found")
+
+            self.auth_state.code = code
+            self.auth_state.event.set()  # Signal that we received the code
+
+            return {"message": "Authentication successful. You can close this window."}
+
+    @property
+    def redirect_uri(self) -> str:
+        """Return redirect uril for server callback."""
+        if not self.port:
+            raise LocalServerError("Server has no port assigned.")
+        return f"http://{HOST}:{self.port}/callback"
+
+    @staticmethod
+    def _find_free_port() -> int:
+        """Bind to port 0 to let the OS select a free port, then return that port."""
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("", 0))
+            return s.getsockname()[1]
+
+    @contextlib.contextmanager
+    def run(self) -> Iterator[Self]:
+        """Start server in a background thread."""
+        self.port = self._find_free_port()
+        config = uvicorn.Config(app=self.app, port=self.port, host=HOST, log_level="error")
+        server = uvicorn.Server(config=config)
+        thread = threading.Thread(target=server.run, daemon=True)
+        try:
+            thread.start()
+            L.info("Local server listening on http://%s:%s", HOST, self.port)
+            yield self
+        finally:
+            L.debug("Stopping the local server")
+            server.should_exit = True
+            thread.join(timeout=1)
+
+    def wait_for_code(self, timeout: int = settings.LOCAL_SERVER_TIMEOUT) -> str:
+        """Wait for code."""
+        if self.auth_state.event.wait(timeout):
+            self.auth_state.event.clear()
+            return self.auth_state.code
+        raise LocalServerError("Timeout waiting for authorization code")

obi_auth-0.0.1/src/obi_auth/typedef.py

@@ -0,0 +1,16 @@
+"""This module provides typedefs for the obi_auth service."""
+
+from enum import StrEnum
+
+
+class DeploymentEnvironment(StrEnum):
+    """Deployment environment."""
+
+    staging = "staging"
+    production = "production"
+
+
+class KeycloakRealm(StrEnum):
+    """Keycloak realms."""
+
+    sbo = "SBO"

obi_auth-0.0.1/src/obi_auth.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: obi_auth
+Version: 0.0.1
+Summary: Python library for retrieving Keycloak access tokens interactively
+Author-email: Open Brain Institute <info@openbraininstitute.org>
+Maintainer-email: Open Brain Institute <info@openbraininstitute.org>
+License: Apache-2.0
+Project-URL: documentation, https://github.com/openbraininstitute/obi-auth
+Project-URL: repository, https://github.com/openbraininstitute/obi-auth
+Project-URL: changelog, https://github.com/openbraininstitute/obi-auth/CHANGELOG.rst
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Dist: pydantic-settings
+Requires-Dist: uvicorn
+Requires-Dist: fastapi
+Dynamic: license-file
+
+[![Build status][build_status_badge]][build_status_target]
+[![License][license_badge]][license_target]
+[![Code coverage][coverage_badge]][coverage_target]
+[![CodeQL][codeql_badge]][codeql_target]
+[![PyPI][pypi_badge]][pypi_target]
+
+# obi-auth
+
+obi-auth is a library for retrieving Keycloak access tokens interactively. It helps developers and testers quickly authenticate against Keycloak without writing scripts or configuring complex clients.
+
+
+## Installation
+
+```sh
+pip install obi-auth
+```
+
+## Examples
+
+```python
+from obi_auth import get_token
+
+access_token = get_token(environment="staging")
+```
+
+## License
+
+Copyright (c) 2025 Open Brain Institute
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+[build_status_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/tox.yml/badge.svg
+[build_status_target]: https://github.com/openbraininstitute/obi-auth/actions
+[license_badge]: https://img.shields.io/pypi/l/obi-auth
+[license_target]: https://github.com/openbraininstitute/obi-auth/blob/main/LICENSE.txt
+[coverage_badge]: https://codecov.io/github/openbraininstitute/obi-auth/coverage.svg?branch=main
+[coverage_target]: https://codecov.io/github/openbraininstitute/obi-auth?branch=main
+[codeql_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/github-code-scanning/codeql/badge.svg
+[codeql_target]: https://github.com/openbraininstitute/obi-auth/actions/workflows/github-code-scanning/codeql
+[pypi_badge]: https://github.com/openbraininstitute/obi-auth/actions/workflows/sdist.yml/badge.svg
+[pypi_target]: https://pypi.org/project/obi-auth/
+

obi_auth-0.0.1/src/obi_auth.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+.gitignore
+CHANGELOG.rst
+LICENSE.txt
+README.md
+pyproject.toml
+tox.ini
+.github/workflows/sdist.yml
+.github/workflows/tox.yml
+src/obi_auth/__init__.py
+src/obi_auth/client.py
+src/obi_auth/config.py
+src/obi_auth/exception.py
+src/obi_auth/flow.py
+src/obi_auth/server.py
+src/obi_auth/typedef.py
+src/obi_auth.egg-info/PKG-INFO
+src/obi_auth.egg-info/SOURCES.txt
+src/obi_auth.egg-info/dependency_links.txt
+src/obi_auth.egg-info/requires.txt
+src/obi_auth.egg-info/top_level.txt
+tests/__init__.py
+tests/unit/__init__.py
+tests/unit/test_client.py
+tests/unit/test_config.py
+tests/unit/test_flow.py
+tests/unit/test_server.py
+tests/unit/data/.gitignore

obi_auth-0.0.1/src/obi_auth.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

obi_auth-0.0.1/src/obi_auth.egg-info/requires.txt

@@ -0,0 +1,5 @@
+httpx
+pydantic
+pydantic-settings
+uvicorn
+fastapi

obi_auth-0.0.1/src/obi_auth.egg-info/top_level.txt

@@ -0,0 +1 @@
+obi_auth

obi_auth-0.0.1/tests/__init__.py

@@ -0,0 +1 @@
+"""obi_auth tests."""

obi_auth-0.0.1/tests/unit/__init__.py

@@ -0,0 +1 @@
+"""obi_auth unit tests."""

obi_auth-0.0.1/tests/unit/test_client.py

@@ -0,0 +1,34 @@
+from unittest.mock import Mock, patch
+
+import pytest
+
+from obi_auth import client as test_module
+from obi_auth import exception
+
+
+@patch("obi_auth.flow.webbrowser")
+@patch("obi_auth.client.AuthServer")
+def test_get_token(mock_server, mock_web, httpx_mock):
+    httpx_mock.add_response(method="POST", json={"access_token": "mock-token"})
+
+    mock_local = Mock()
+    mock_local.redirect_uri = "mock-redirect-uri"
+    mock_local.wait_for_code.return_value = "mock-code"
+    mock_server.run.return_value.__enter__.return_value = mock_local
+
+    res = test_module.get_token()
+    assert res == "mock-token"
+
+    mock_server.side_effect = exception.AuthFlowError()
+    with pytest.raises(exception.ClientError, match="Authentication process failed."):
+        test_module.get_token()
+
+    mock_server.side_effect = exception.ConfigError()
+    with pytest.raises(
+        exception.ClientError, match="There is a mistake with configuration settings."
+    ):
+        test_module.get_token()
+
+    mock_server.side_effect = exception.LocalServerError()
+    with pytest.raises(exception.ClientError, match="Local server failed to authenticate."):
+        test_module.get_token()

obi_auth-0.0.1/tests/unit/test_config.py

@@ -0,0 +1,57 @@
+import pytest
+
+from obi_auth import config as test_module
+from obi_auth import exception
+
+
+@pytest.fixture
+def settings(monkeypatch):
+    monkeypatch.setenv("KEYCLOAK_ENV", "staging")
+    monkeypatch.setenv("KEYCLOAK_REALM", "SBO")
+    return test_module.Settings()
+
+
+def test_get_keycloak_url(settings):
+    res = settings.get_keycloak_url()
+    assert res == "https://staging.openbraininstitute.org/auth/realms/SBO"
+
+    res = settings.get_keycloak_url(override_env="staging")
+    assert res == "https://staging.openbraininstitute.org/auth/realms/SBO"
+
+    res = settings.get_keycloak_url(override_env="production")
+    assert res == "https://openbraininstitute.org/auth/realms/SBO"
+
+    with pytest.raises(exception.ConfigError, match="Unknown deployment environment foo"):
+        settings.get_keycloak_url(override_env="foo")
+
+
+def test_get_keycloak_token_endpoint(settings):
+    res = settings.get_keycloak_token_endpoint()
+    assert (
+        res
+        == "https://staging.openbraininstitute.org/auth/realms/SBO/protocol/openid-connect/token"
+    )
+
+    res = settings.get_keycloak_token_endpoint(override_env="staging")
+    assert (
+        res
+        == "https://staging.openbraininstitute.org/auth/realms/SBO/protocol/openid-connect/token"
+    )
+
+    res = settings.get_keycloak_token_endpoint(override_env="production")
+    assert res == "https://openbraininstitute.org/auth/realms/SBO/protocol/openid-connect/token"
+
+
+def test_get_keycloak_auth_endpoint(settings):
+    res = settings.get_keycloak_auth_endpoint()
+    assert (
+        res == "https://staging.openbraininstitute.org/auth/realms/SBO/protocol/openid-connect/auth"
+    )
+
+    res = settings.get_keycloak_auth_endpoint(override_env="staging")
+    assert (
+        res == "https://staging.openbraininstitute.org/auth/realms/SBO/protocol/openid-connect/auth"
+    )
+
+    res = settings.get_keycloak_auth_endpoint(override_env="production")
+    assert res == "https://openbraininstitute.org/auth/realms/SBO/protocol/openid-connect/auth"

obi_auth-0.0.1/tests/unit/test_flow.py

@@ -0,0 +1,45 @@
+from unittest.mock import Mock, patch
+
+from obi_auth import flow as test_module
+
+
+def test_build_auth_url():
+    res = test_module._build_auth_url(
+        code_challenge="foo",
+        redirect_uri="bar",
+        override_env=None,
+    )
+    assert res == (
+        "https://staging.openbraininstitute.org/auth/realms/SBO/protocol/openid-connect/auth"
+        "?response_type=code"
+        "&client_id=obi-entitysdk-auth"
+        "&redirect_uri=bar"
+        "&scope=openid"
+        "&code_challenge=foo"
+        "&code_challenge_method=S256"
+        "&kc_idp_hint=github"
+    )
+
+
+def test_exchange_code_for_token(httpx_mock):
+    httpx_mock.add_response(method="POST", json={"access_token": "mock-token"})
+    res = test_module._exchange_code_for_token(
+        code="mock-code",
+        redirect_uri="mock-uri",
+        code_verifier="mock-verifier",
+        override_env=None,
+    )
+    assert res == "mock-token"
+
+
+@patch("obi_auth.flow.webbrowser")
+def test_authorize(mocked_webbrowser):
+    mock_server = Mock()
+    mock_server.wait_for_code.return_value = "mock-code"
+
+    res = test_module._authorize(
+        server=mock_server,
+        code_challenge="mock-challenge",
+        override_env=None,
+    )
+    assert res == "mock-code"

obi_auth-0.0.1/tests/unit/test_server.py

@@ -0,0 +1,46 @@
+import httpx
+import pytest
+
+from obi_auth import server as test_module
+from obi_auth.exception import LocalServerError
+from obi_auth.server import AuthServer
+
+
+@pytest.fixture
+def server():
+    return test_module.AuthServer()
+
+
+@pytest.fixture
+def running_server(server):
+    with server.run() as local_server:
+        yield local_server
+
+
+def test_server(server):
+    assert isinstance(server, AuthServer)
+
+
+def test_find_free_port():
+    assert AuthServer._find_free_port() > 0
+
+
+def test_redirect_uri(server):
+    with pytest.raises(LocalServerError, match="Server has no port assigned."):
+        _ = server.redirect_uri
+    server.port = "8000"
+    assert server.redirect_uri == f"http://localhost:{server.port}/callback"
+
+
+def test_wait_for_code(running_server):
+    with pytest.raises(LocalServerError, match="Timeout waiting for authorization code"):
+        running_server.wait_for_code(timeout=0.1)
+
+    response = httpx.get(f"{running_server.redirect_uri}")
+    assert response.status_code == 400
+
+    response = httpx.get(f"{running_server.redirect_uri}?code=mock-code")
+    response.raise_for_status()
+
+    res = running_server.wait_for_code()
+    assert res == "mock-code"

obi_auth-0.0.1/tox.ini

@@ -0,0 +1,49 @@
+[base]
+name = obi_auth
+path = src/{[base]name}
+testdeps =
+    pytest
+    pytest-cov
+    pytest-httpx
+    coverage[toml]
+
+[tox]
+envlist =
+    lint
+    check-packaging
+    py{311,312,313}
+
+minversion = 3.18
+
+[testenv]
+deps =
+    {[base]testdeps}
+commands =
+    python -m pytest {posargs}
+    python -m coverage xml
+    python -m coverage html
+
+[testenv:lint]
+deps =
+    ruff
+    mypy
+commands =
+	python -m ruff format --check
+	python -m ruff check
+    python -m mypy src
+
+[testenv:format]
+deps =
+    ruff
+commands =
+	python -m ruff format
+	python -m ruff check --fix
+
+[testenv:check-packaging]
+skip_install = true
+deps =
+    build
+    twine
+commands =
+    python -m build -o {envtmpdir}/dist
+    twine check {envtmpdir}/dist/*