easy-oauth 0.0.4__tar.gz

easy_oauth-0.0.4/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: easy-oauth
+Version: 0.0.4
+Summary: Easy OAuth authentication for Starlette/FastAPI apps
+Author: Olivier Breuleux
+Author-email: Olivier Breuleux <breuleux@gmail.com>
+License-Expression: MIT
+Requires-Dist: authlib>=1.6.5
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: itsdangerous>=2.2.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: serieux>=0.3.5
+Requires-Dist: starlette>=0.50.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+
+# easy-oauth
+
+Small package to add OAuth-based authentication to a Starlette/FastAPI app. Users may also retrieve a token to authenticate themselves.
+
+
+## Install
+
+`uv add git+https://github.com/mila-iqia/easy-oauth@v0.0.2`
+
+
+## Usage
+
+If you want to authenticate through Google, first you will need to create a project in GCP and get a client_id and client_secret from the console. Then you can do it like this:
+
+
+```python
+from easy_oauth import OAuthManager, CapabilitySet
+
+oauth = OAuthManager(
+    # This page describes where the endpoint urls are defined
+    server_metadata_url="https://accounts.google.com/.well-known/openid-configuration",
+    # A secret key to encrypt the session and tokens, you can generate it yourself
+    secret_key=SECRET_KEY,
+    # The client id from Google Console
+    client_id=CLIENT_ID,
+    # The client secret from Google Console
+    client_secret=CLIENT_SECRET,
+    # Arguments to the auth request, you can just use what's below
+    client_kwargs={
+        "scope": "openid email",
+        "prompt": "select_account",
+    }
+    # Set of capabilities that can be assigned to users
+    capabilities=CapabilitySet(
+        graph={
+            # Basic capability
+            "read": [],
+            # write, also implies read
+            "write": ["read"],
+            # moderate, also implies read and write
+            "moderate": ["read", "write"],
+            # announce, also implies read and write
+            "announce": ["read", "write"],
+            # "user_management" is the capability needed to set the capabilities of
+            # users.
+            "user_management": [],
+        },
+        # Create the "admin" capability that has every other capability
+        auto_admin=True,
+        # File where each user's capability is stored
+        user_file="caps.yaml",
+        # Capabilities granted to all authenticated users
+        default_capabilities=["read"],
+        # Capabilities granted to unauthenticated users (guests)
+        guest_capabilities=[],
+    ),
+    # If you want routes to be at /api/v1/login etc., put "/api/v1" here
+    prefix="",
+)
+
+app = FastAPI()
+
+oauth.install(app)
+```
+
+Here is an example of a user capability file:
+
+```yaml
+your-email@you.com:
+  - admin
+friend@rainbows.com:
+  - moderate
+  - announce
+pierre-jean-jacques@youhou.fr:
+  - read
+hateful-being@cornhole.co: []
+```
+
+In order to require a certain capability for a given route, you can declare it like this in FastAPI:
+
+```python
+@app.get("/shout")
+async def route_shout(
+    request: Request,
+    message: str,
+    email: str = Depends(oauth.get_email_capability("announce", redirect=True)),
+):
+    return PlainTextResponse(f"{email} shouts {message!r}")
+```
+
+If `redirect=True` in `get_email_capability`, then the browser will redirect to the login page if the user is not logged in, then it will redirect back to the original page.
+
+
+### Token workflow
+
+First, the user should point their browser to the `/token` endpoint. This will prompt them to log in and it will display a token. Copy it.
+
+Then you can use use Bearer authentication with the token. That is to say, the `Authorization` header should be set to `Bearer INSERT_TOKEN_HERE`. Using `httpx`, for example (it should work the same with `requests`):
+
+```python
+# Unauthorized access
+assert httpx.get(f"{app_url}/something").status_code == 401
+
+# Authorized access
+assert httpx.get(f"{app_url}/something", headers={"Authorization": f"Bearer {token}"}).status_code == 200
+```
+
+
+### Reading configuration from a file
+
+The configuration for the above OAuthManager can be written in a file, like this:
+
+```yaml
+server_metadata_url: https://accounts.google.com/.well-known/openid-configuration
+secret_key: "<SECRET_KEY>"
+client_id: "<CLIENT_ID>"
+client_secret: "<CLIENT_SECRET>"
+client_kwargs:
+  scope: openid email
+  prompt: select_account
+capabilities:
+  graph:
+    read: []
+    write: [read]
+    moderate: [read, write]
+    announce: [read, write]
+    user_management: []
+  auto_admin: true
+  user_file: caps.yaml
+  default_capabilities: [read]
+  guest_capabilities: []
+prefix: ""
+```
+
+And instantiated like this:
+
+```python
+from serieux import deserialize
+
+oauth = deserialize(OAuthManager, Path("config.yaml"))
+```
+
+Of course, you can nest that configuration within a larger configuration.
+
+
+### Encrypting the configuration
+
+The secrets written in the config file can be encrypted using `serieux` (The `-m` option must point to the type of the root of the configuration using the syntax `module:symbol`, in this case it is simply `easy_oauth:OAuthManager`):
+
+```bash
+export SERIEUX_PASSWORD="change_me!!1"
+serieux patch -m easy_oauth:OAuthManager -f config.yaml
+```
+
+You must then modify the instantiation code like this:
+
+```python
+import os
+from serieux import deserialize
+from serieux.features.encrypt import EncryptionKey
+
+oauth = deserialize(OAuthManager, Path("config.yaml"), EncryptionKey(os.getenv("SERIEUX_PASSWORD")))
+```
+
+## Routes
+
+The OAuthManager automatically adds the following routes when installed on your Starlette/FastAPI application:
+
+### Authentication Routes
+
+- **GET `/login`**
+  - Initiates the OAuth login flow
+  - Clears the current session and redirects to the OAuth provider
+  - Query parameters:
+    - `redirect` (optional): Name of the auth callback route (default: `auth`)
+    - `offline_token=true` (optional): Request a refresh token with offline access
+  - Stores the original URL in session to redirect back after authentication
+
+- **GET `/auth`**
+  - OAuth callback route that handles the authorization code
+  - Exchanges the authorization code for tokens and stores user information in the session
+  - Redirects to the original URL (default: `/`)
+
+- **GET `/token`**
+  - Returns an encrypted refresh token for the authenticated user
+  - Response: `{"refresh_token": "<encrypted_token>"}`
+
+- **GET `/logout`**
+  - Clears the user session and redirects to `/`
+
+### Capability Management Routes
+
+- **GET `/manage_capabilities/list`**
+  - Lists capabilities for a user
+  - Query parameters:
+    - `email` (optional): Email address to query (defaults to current user)
+  - Requires user management capability if querying another user's capabilities
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+The following routes are only added if there is a `user_management` capability:
+
+- **POST `/manage_capabilities/add`**
+  - Adds a capability to a user
+  - Requires user management capability
+  - Request body: `{"email": "<email>", "capability": "<capability_name>"}`
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+- **POST `/manage_capabilities/remove`**
+  - Removes a capability from a user
+  - Requires user management capability
+  - Request body: `{"email": "<email>", "capability": "<capability_name>"}`
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+- **POST `/manage_capabilities/set`**
+  - Sets the complete capability set for a user (replaces existing capabilities)
+  - Requires user management capability
+  - Request body: `{"email": "<email>", "capabilities": ["<cap1>", "<cap2>", ...]}`
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+
+## Testing
+
+For testing, easy_oauth defines a mock OAuth server that always logs you in unconditionally as `test@example.com` by default. That way you don't need a browser or any secrets to test things.
+
+```bash
+uvicorn easy_oauth.testing.oauth_mock:app
+```
+
+To set the email address the mock OAuth server with authentify all requests as, send a POST request with JSON data like this:
+
+```bash
+curl -X POST -H "Content-Type: application/json" -d '{"email": "a@b.c"}' http://127.0.0.1:8000/set_email
+```
+
+To use it with easy_oauth, set `server_metadata_url` to `http://127.0.0.1:8000/.well-known/openid-configuration` (depending on the host and port).
+
+
+### Fixtures
+
+easy-oauth provides the `OAuthMock` and `AppTester` classes to make testing easier. Here is a very simple example of how to use them:
+
+
+```python
+from easy_oauth.testing.utils import AppTester, OAuthMock
+
+@pytest.fixture(scope="session")
+def oauth_mock():
+    # Start one mock oauth server for the session. It's important that the
+    # OAUTH_PORT conforms to the server_metadata_url you configure the test app
+    # with
+    with OAuthMock(port=OAUTH_PORT) as oauth:
+        yield oauth
+
+@pytest.fixture(scope="session")
+def app(oauth_mock):
+    # This doesn't have to be session-scoped, but if your app is read-only it may
+    # as well be.
+    with AppTester(your_app, oauth_mock) as appt:
+        yield appt
+
+def test_view_payroll(app):
+    # Use app.client to pretend to be various users
+    guest = app.client()
+    user = app.client("simple.user@website.web")
+    accountant = app.client("mr.bean@website.web")
+    admin = app.client("admin@website.web")
+
+    # Guests are not authentified (so we expect HTTP error 401)
+    guest.get("/payroll/view", expect=401)
+    # Normal users are unauthorized to view the payroll
+    user.get("/payroll/view", expect=403)
+    # Accountants and admins are authorized
+    accountant.get("/payroll/view", expect=200)
+    admin.get("/payroll/view", expect=200)
+```
+
+
+## TODO
+
+There are a few things that need to be done in the future:
+
+* Add an endpoint to revoke tokens.
+* Users with `user_management` capability should only be able to add/remove capabilities that they have.
+* API tokens associated to capabilities but not accounts

easy_oauth-0.0.4/README.md

@@ -0,0 +1,285 @@
+
+# easy-oauth
+
+Small package to add OAuth-based authentication to a Starlette/FastAPI app. Users may also retrieve a token to authenticate themselves.
+
+
+## Install
+
+`uv add git+https://github.com/mila-iqia/easy-oauth@v0.0.2`
+
+
+## Usage
+
+If you want to authenticate through Google, first you will need to create a project in GCP and get a client_id and client_secret from the console. Then you can do it like this:
+
+
+```python
+from easy_oauth import OAuthManager, CapabilitySet
+
+oauth = OAuthManager(
+    # This page describes where the endpoint urls are defined
+    server_metadata_url="https://accounts.google.com/.well-known/openid-configuration",
+    # A secret key to encrypt the session and tokens, you can generate it yourself
+    secret_key=SECRET_KEY,
+    # The client id from Google Console
+    client_id=CLIENT_ID,
+    # The client secret from Google Console
+    client_secret=CLIENT_SECRET,
+    # Arguments to the auth request, you can just use what's below
+    client_kwargs={
+        "scope": "openid email",
+        "prompt": "select_account",
+    }
+    # Set of capabilities that can be assigned to users
+    capabilities=CapabilitySet(
+        graph={
+            # Basic capability
+            "read": [],
+            # write, also implies read
+            "write": ["read"],
+            # moderate, also implies read and write
+            "moderate": ["read", "write"],
+            # announce, also implies read and write
+            "announce": ["read", "write"],
+            # "user_management" is the capability needed to set the capabilities of
+            # users.
+            "user_management": [],
+        },
+        # Create the "admin" capability that has every other capability
+        auto_admin=True,
+        # File where each user's capability is stored
+        user_file="caps.yaml",
+        # Capabilities granted to all authenticated users
+        default_capabilities=["read"],
+        # Capabilities granted to unauthenticated users (guests)
+        guest_capabilities=[],
+    ),
+    # If you want routes to be at /api/v1/login etc., put "/api/v1" here
+    prefix="",
+)
+
+app = FastAPI()
+
+oauth.install(app)
+```
+
+Here is an example of a user capability file:
+
+```yaml
+your-email@you.com:
+  - admin
+friend@rainbows.com:
+  - moderate
+  - announce
+pierre-jean-jacques@youhou.fr:
+  - read
+hateful-being@cornhole.co: []
+```
+
+In order to require a certain capability for a given route, you can declare it like this in FastAPI:
+
+```python
+@app.get("/shout")
+async def route_shout(
+    request: Request,
+    message: str,
+    email: str = Depends(oauth.get_email_capability("announce", redirect=True)),
+):
+    return PlainTextResponse(f"{email} shouts {message!r}")
+```
+
+If `redirect=True` in `get_email_capability`, then the browser will redirect to the login page if the user is not logged in, then it will redirect back to the original page.
+
+
+### Token workflow
+
+First, the user should point their browser to the `/token` endpoint. This will prompt them to log in and it will display a token. Copy it.
+
+Then you can use use Bearer authentication with the token. That is to say, the `Authorization` header should be set to `Bearer INSERT_TOKEN_HERE`. Using `httpx`, for example (it should work the same with `requests`):
+
+```python
+# Unauthorized access
+assert httpx.get(f"{app_url}/something").status_code == 401
+
+# Authorized access
+assert httpx.get(f"{app_url}/something", headers={"Authorization": f"Bearer {token}"}).status_code == 200
+```
+
+
+### Reading configuration from a file
+
+The configuration for the above OAuthManager can be written in a file, like this:
+
+```yaml
+server_metadata_url: https://accounts.google.com/.well-known/openid-configuration
+secret_key: "<SECRET_KEY>"
+client_id: "<CLIENT_ID>"
+client_secret: "<CLIENT_SECRET>"
+client_kwargs:
+  scope: openid email
+  prompt: select_account
+capabilities:
+  graph:
+    read: []
+    write: [read]
+    moderate: [read, write]
+    announce: [read, write]
+    user_management: []
+  auto_admin: true
+  user_file: caps.yaml
+  default_capabilities: [read]
+  guest_capabilities: []
+prefix: ""
+```
+
+And instantiated like this:
+
+```python
+from serieux import deserialize
+
+oauth = deserialize(OAuthManager, Path("config.yaml"))
+```
+
+Of course, you can nest that configuration within a larger configuration.
+
+
+### Encrypting the configuration
+
+The secrets written in the config file can be encrypted using `serieux` (The `-m` option must point to the type of the root of the configuration using the syntax `module:symbol`, in this case it is simply `easy_oauth:OAuthManager`):
+
+```bash
+export SERIEUX_PASSWORD="change_me!!1"
+serieux patch -m easy_oauth:OAuthManager -f config.yaml
+```
+
+You must then modify the instantiation code like this:
+
+```python
+import os
+from serieux import deserialize
+from serieux.features.encrypt import EncryptionKey
+
+oauth = deserialize(OAuthManager, Path("config.yaml"), EncryptionKey(os.getenv("SERIEUX_PASSWORD")))
+```
+
+## Routes
+
+The OAuthManager automatically adds the following routes when installed on your Starlette/FastAPI application:
+
+### Authentication Routes
+
+- **GET `/login`**
+  - Initiates the OAuth login flow
+  - Clears the current session and redirects to the OAuth provider
+  - Query parameters:
+    - `redirect` (optional): Name of the auth callback route (default: `auth`)
+    - `offline_token=true` (optional): Request a refresh token with offline access
+  - Stores the original URL in session to redirect back after authentication
+
+- **GET `/auth`**
+  - OAuth callback route that handles the authorization code
+  - Exchanges the authorization code for tokens and stores user information in the session
+  - Redirects to the original URL (default: `/`)
+
+- **GET `/token`**
+  - Returns an encrypted refresh token for the authenticated user
+  - Response: `{"refresh_token": "<encrypted_token>"}`
+
+- **GET `/logout`**
+  - Clears the user session and redirects to `/`
+
+### Capability Management Routes
+
+- **GET `/manage_capabilities/list`**
+  - Lists capabilities for a user
+  - Query parameters:
+    - `email` (optional): Email address to query (defaults to current user)
+  - Requires user management capability if querying another user's capabilities
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+The following routes are only added if there is a `user_management` capability:
+
+- **POST `/manage_capabilities/add`**
+  - Adds a capability to a user
+  - Requires user management capability
+  - Request body: `{"email": "<email>", "capability": "<capability_name>"}`
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+- **POST `/manage_capabilities/remove`**
+  - Removes a capability from a user
+  - Requires user management capability
+  - Request body: `{"email": "<email>", "capability": "<capability_name>"}`
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+- **POST `/manage_capabilities/set`**
+  - Sets the complete capability set for a user (replaces existing capabilities)
+  - Requires user management capability
+  - Request body: `{"email": "<email>", "capabilities": ["<cap1>", "<cap2>", ...]}`
+  - Response: `{"status": "ok", "email": "<email>", "capabilities": [...]}`
+
+
+## Testing
+
+For testing, easy_oauth defines a mock OAuth server that always logs you in unconditionally as `test@example.com` by default. That way you don't need a browser or any secrets to test things.
+
+```bash
+uvicorn easy_oauth.testing.oauth_mock:app
+```
+
+To set the email address the mock OAuth server with authentify all requests as, send a POST request with JSON data like this:
+
+```bash
+curl -X POST -H "Content-Type: application/json" -d '{"email": "a@b.c"}' http://127.0.0.1:8000/set_email
+```
+
+To use it with easy_oauth, set `server_metadata_url` to `http://127.0.0.1:8000/.well-known/openid-configuration` (depending on the host and port).
+
+
+### Fixtures
+
+easy-oauth provides the `OAuthMock` and `AppTester` classes to make testing easier. Here is a very simple example of how to use them:
+
+
+```python
+from easy_oauth.testing.utils import AppTester, OAuthMock
+
+@pytest.fixture(scope="session")
+def oauth_mock():
+    # Start one mock oauth server for the session. It's important that the
+    # OAUTH_PORT conforms to the server_metadata_url you configure the test app
+    # with
+    with OAuthMock(port=OAUTH_PORT) as oauth:
+        yield oauth
+
+@pytest.fixture(scope="session")
+def app(oauth_mock):
+    # This doesn't have to be session-scoped, but if your app is read-only it may
+    # as well be.
+    with AppTester(your_app, oauth_mock) as appt:
+        yield appt
+
+def test_view_payroll(app):
+    # Use app.client to pretend to be various users
+    guest = app.client()
+    user = app.client("simple.user@website.web")
+    accountant = app.client("mr.bean@website.web")
+    admin = app.client("admin@website.web")
+
+    # Guests are not authentified (so we expect HTTP error 401)
+    guest.get("/payroll/view", expect=401)
+    # Normal users are unauthorized to view the payroll
+    user.get("/payroll/view", expect=403)
+    # Accountants and admins are authorized
+    accountant.get("/payroll/view", expect=200)
+    admin.get("/payroll/view", expect=200)
+```
+
+
+## TODO
+
+There are a few things that need to be done in the future:
+
+* Add an endpoint to revoke tokens.
+* Users with `user_management` capability should only be able to add/remove capabilities that they have.
+* API tokens associated to capabilities but not accounts

easy_oauth-0.0.4/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "easy-oauth"
+version = "0.0.4"
+description = "Easy OAuth authentication for Starlette/FastAPI apps"
+readme = "README.md"
+authors = [
+    { name = "Olivier Breuleux", email = "breuleux@gmail.com" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "authlib>=1.6.5",
+    "httpx>=0.28.1",
+    "itsdangerous>=2.2.0",
+    "pyyaml>=6.0.3",
+    "serieux>=0.3.5",
+    "starlette>=0.50.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "fastapi>=0.121.3",
+    "pytest>=9.0.1",
+    "pytest-cov>=7.0.0",
+    "pytest-freezer>=0.4.9",
+    "python-multipart>=0.0.20",
+    "uvicorn>=0.38.0",
+]
+
+[tool.ruff]
+line-length = 99
+
+[tool.ruff.lint]
+extend-select = ["I"]
+ignore = ["E241", "F722", "E501", "E203", "F811", "F821"]
+
+[tool.coverage.run]
+omit = [
+    "src/easy_oauth/testing/*"
+]

easy_oauth-0.0.4/src/easy_oauth/__init__.py

@@ -0,0 +1,4 @@
+from .cap import Capability, CapabilitySet
+from .manager import OAuthManager
+
+__all__ = ["Capability", "CapabilitySet", "OAuthManager"]