Merge pull request #4 from pytest-dev/create-prompt

Implement an embedded test client

Author: azmeuk

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Versions follow [Semantic Versioning](https://semver.org/>) (<major>.<minor>.<patch>).
 
+## [0.2.0] - Unreleased
+
+### Added
+
+- Implement `test_client` attribute.
+- Implement `logout` method.
+- Support for OIDC `create` prompt.
+
 ## [0.1.1] - 2025-04-04
 
 ### Changed

README.md

@@ -36,19 +36,19 @@ def test_authentication(iam_server, testapp, client):
     # create a random user on the IAM server
     user = iam_server.random_user()
 
-    # logs the user in give its consent to your application
-    iam_server.login(user)
-    iam_server.consent(user)
+    # 1. attempt to access a protected page, returns a redirection to the IAM
+    res = test_client.get("/protected")
 
-    # simulate an attempt to access a protected page of your app
-    response = testapp.get("/protected", status=302)
+    # 2. authorization code request
+    res = iam_server.test_client.get(res.location)
 
-    # get an authorization code request at the IAM
-    res = requests.get(res.location, allow_redirects=False)
+    # 3. load your application authorization endpoint
+    res = test_client.get(res.location)
 
-    # access to the redirection URI
-    res = testclient.get(res.headers["Location"])
-    res.mustcontain("Hello World!")
+    # 4. now you have access to the protected page
+    res = test_client.get("/protected")
+
+    assert "Hello, world!" in res.text
 ```
 
 Check the [client application](https://pytest-iam.readthedocs.io/en/latest/client-applications.html) or

doc/client-applications.rst

@@ -94,8 +94,8 @@ client registration. Here is an example of dynamic registration you can implemen
 
 .. code:: python
 
-    response = requests.post(
-        f"{iam_server.url}/oauth/register",
+    response = iam_server.test_client.post(
+        "/oauth/register",
         json={
             "client_name": "My application",
             "client_uri": "http://example.org",
@@ -106,56 +106,82 @@ client registration. Here is an example of dynamic registration you can implemen
             "scope": "openid profile groups",
         },
     )
-    client_id = response.json()["client_id"]
-    client_secret = response.json()["client_secret"]
+    client_id = response.json["client_id"]
+    client_secret = response.json["client_secret"]
 
-Nominal authentication case
----------------------------
+Nominal authentication workflow
+-------------------------------
 
 Let us suppose that your application have a ``/protected`` that redirects users
-to the IAM server if unauthenticated. With your :class:`~canaille.core.models.User`
-and :class:`~canaille.oidc.models.Client` fixtures, you can use the
-:meth:`~pytest_iam.Server.login` and :meth:`~pytest_iam.Server.consent` methods
-to skip the login and the consent page from the IAM.
-
+to the IAM server if unauthenticated.
 We suppose you have a test client fixture like werkzeug :class:`~werkzeug.test.Client`
-that allows to test your application endpoints without real HTTP requests. Let
-us see how to implement an authorization_code authentication test case:
+that allows to test your application endpoints without real HTTP requests.
+pytest-iam provides its own test client, available with :meth:`~pytest_iam.Server.test_client`.
+Let us see how to implement an authorization_code authentication test case:
 
-.. code:: python
+.. code-block:: python
+   :caption: Full login and consent workflow to get an access token
+
+    def test_login_and_consent(iam_server, client, user, test_client):
+        # 1. attempt to access a protected page
+        res = test_client.get("/protected")
+
+        # 2. redirect to the authorization server login page
+        res = iam_server.test_client.get(res.location)
+
+        # 3. fill the 'login' form at the IAM
+        res = iam_server.test_client.post(res.location, data={"login": "user"})
+
+        # 4. fill the 'password' form at the IAM
+        res = iam_server.test_client.post(
+            res.location, data={"password": "correct horse battery staple"}
+        )
+
+        # 5. fill the 'consent' form at the IAM
+        res = iam_server.test_client.post(res.location, data={"answer": "accept"})
+
+        # 6. load your application authorization endpoint
+        res = test_client.get(res.location)
+
+        # 7. now you have access to the protected page
+        res = test_client.get("/protected")
+
+What happened?
+
+1. A simulation of an access to a protected page on your application. As the page is protected,
+   it returns a redirection to the IAM login page.
+2. The IAM test client loads the login page and get redirected to the login form.
+3. The login form is filled, and returns a redirection to the password form.
+4. The password form is filled, and returns a redirection to the consent form.
+5. The consent form is filled, and return a redirection to your application authorization endpoint with a OAuth code grant.
+6. You client authorization endpoint is loaded, it reaches the IAM and exchanges the code grant with a token.   This is generally where you fill the session to keep users logged in.
+7. The protected page is loaded, and now you should be able to access it.
+
+Steps 2, 3 and 4 can be quite redundant, so pytest-iam provides shortcuts with the
+:meth:`~pytest_iam.Server.login` and :meth:`~pytest_iam.Server.consent` methods.
+They allow you to skip the login, password and consent pages:
+
+.. code-block:: python
+   :caption: Fast login and consent workflow to get an access token
 
-    def test_login_and_consent(iam_server, client, user, testclient):
+    def test_login_and_consent(iam_server, client, user, test_client):
         iam_server.login(user)
         iam_server.consent(user)
 
         # 1. attempt to access a protected page
-        res = testclient.get("/protected", status=302)
+        res = test_client.get("/protected")
 
         # 2. authorization code request
-        res = requests.get(res.location, allow_redirects=False)
+        res = iam_server.test_client.get(res.location)
 
         # 3. load your application authorization endpoint
-        res = testclient.get(res.headers["Location"], status=302)
+        res = test_client.get(res.location)
 
-        # 4. redirect to the protected page
-        res = res.follow(status=200)
+        # 4. now you have access to the protected page
+        res = test_client.get("/protected")
 
-What happened?
-
-1. A simulation of an access to a protected page on your application.
-2. That redirects to the IAM authorization endpoint. Since the users are already
-   logged and their consent already given, the IAM redirects to your application
-   authorization configured redirect_uri, with the authorization code passed in
-   the query string. Note that ``requests`` is used in this example to perform
-   the request. Indeed, generally testclient such as the werkzeug one cannot
-   perform real HTTP requests.
-3. Access your application authorization endpoint that will exchange the
-   authorization code against a token and check the user credentials.
-4. For instance, your application can redirect the users back to the page
-   they attempted to access in the first place.
-
-Error cases
------------
+Authentication workflow errors
+------------------------------
 
 The `OAuth2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ and the `OpenID Connect <https://openid.net/specs/openid-connect-core-1_0.html>`_ specifications details how things might go wrong:
 
@@ -183,3 +209,49 @@ The `OIDC error codes <https://openid.net/specs/openid-connect-core-1_0.html#Aut
 
 You might or might not be interested in testing how your application behaves when it encounters those situations,
 depending on the situation and how much you trust the libraries that helps your application perform the authentication process.
+
+Account creation workflow
+-------------------------
+
+The `Initiating User Registration via OpenID Connect 1.0 <https://openid.net/specs/openid-connect-prompt-create-1_0.html>`_
+specification details how to initiate an account creation workflow at the IAM
+by setting the ``prompt=create`` authorization request parameter.
+
+In the following example, we suppose that the ``/create`` endpoint redirects
+to the IAM authorization endpoint with the ``prompt=create`` parameters.
+
+.. code-block:: python
+    :caption: Account creation workflow
+
+    def test_account_creation(iam_server, client, test_client):
+        # access to the client account creation page
+        res = test_client.get("/create")
+
+        # redirection to the IAM account creation page
+        res = iam_server.test_client.get(res.location)
+
+        # redirection to the account creation page
+        res = iam_server.test_client.get(res.location)
+
+        payload = {
+            "user_name": "user",
+            "given_name": "John",
+            "family_name": "Doe",
+            "emails-0": "email@example.com",
+            "preferred_language": "auto", # appears to be mandatory
+            "password1": "correct horse battery staple",
+            "password2": "correct horse battery staple",
+        }
+
+        # fill the registration form
+        res = iam_server.test_client.post(res.location, data=payload)
+
+        # fill the 'consent' form
+        res = iam_server.test_client.post(res.location, data={"answer": "accept"})
+
+        # return to the client with a code
+        res = test_client.get(res.location)
+
+        assert "User account successfully created" in res.text
+
+Unfortunately there is no helpers for account creation in the fashion of :meth:`~pytest_iam.Server.login`.

doc/resource-servers.rst

@@ -8,16 +8,16 @@ request against the identity server token introspection endpoint.
 
 .. code:: python
 
-    def test_valid_token_auth(iam_server, testclient, client, user):
+    def test_valid_token_auth(iam_server, test_client, client, user):
         token = iam_server.random_token(client=client, subject=user)
-        res = testclient.get(
+        res = test_client.get(
             "/protected-resource", headers={"Authorization": f"Bearer {token.access_token}"}
         )
         assert res.status_code == 200
 
 
-    def test_invalid_token_auth(iam_server, testclient):
-        res = testclient.get(
+    def test_invalid_token_auth(iam_server, test_client):
+        res = test_client.get(
             "/protected-resource", headers={"Authorization": "Bearer invalid"}
         )
         assert res.status_code == 401

pyproject.toml

@@ -31,7 +31,7 @@ documentation = "https://pytest-iam.readthedocs.io/en/latest/"
 
 requires-python = ">=3.10"
 dependencies = [
-    "canaille[oidc]>=0.0.71",
+    "canaille[oidc]>=0.0.74",
     "portpicker>=1.6.0",
     "pytest>=7.0.0",
     "faker>=21.0.0",

pytest_iam/__init__.py

@@ -20,6 +20,7 @@
 from canaille.oidc.installation import generate_keypair
 from flask import Flask
 from flask import g
+from werkzeug.test import Client
 
 
 class Server:
@@ -31,6 +32,9 @@ class Server:
     app: Flask
     """The authorization server flask app."""
 
+    test_client: Client
+    """A test client to interact with the IAM without performing real network requests."""
+
     models: ModuleType
     """The module containing the available model classes."""
 
@@ -40,8 +44,9 @@ class Server:
     logging: bool = False
     """Whether the request access log is enabled."""
 
-    def __init__(self, app, port: int, backend: Backend, logging: bool = False):
+    def __init__(self, app: Flask, port: int, backend: Backend, logging: bool = False):
         self.app = app
+        self.test_client = app.test_client()
         self.backend = backend
         self.port = port
         self.logging = logging
@@ -50,11 +55,25 @@ def __init__(self, app, port: int, backend: Backend, logging: bool = False):
         )
         self.models = models
         self.logged_user = None
+        self.login_datetime = None
 
         @self.app.before_request
         def logged_user():
             if self.logged_user:
                 g.user = self.logged_user
+            else:
+                try:
+                    del g.user
+                except AttributeError:
+                    pass
+
+            if self.login_datetime:
+                g.last_login_datetime = self.login_datetime
+            else:
+                try:
+                    del g.last_login_datetime
+                except AttributeError:
+                    pass
 
     def make_request_handler(self):
         server = self
@@ -125,6 +144,12 @@ def login(self, user):
         This allows to skip the connection screen.
         """
         self.logged_user = user
+        self.login_datetime = datetime.datetime.now(datetime.timezone.utc)
+
+    def logout(self):
+        """Close the current user session if existing."""
+        self.logged_user = None
+        self.login_datetime = None
 
     def consent(self, user, client=None):
         """Make a user consent to share data with OIDC clients.
@@ -172,6 +197,7 @@ def iam_configuration(tmp_path_factory, iam_server_port) -> dict[str, Any]:
         "WTF_CSRF_ENABLED": False,
         "SERVER_NAME": f"localhost:{iam_server_port}",
         "CANAILLE": {
+            "ENABLE_REGISTRATION": True,
             "JAVASCRIPT": False,
             "ACL": {
                 "DEFAULT": {

tests/conftest.py

@@ -25,7 +25,7 @@ def user(iam_server):
         user_name="user",
         formatted_name="John Doe",
         emails=["email@example.com"],
-        password="password",
+        password="correct horse battery staple",
     )
     iam_server.backend.save(inst)
     yield inst