From 72d98be9f085fe8212d6cd67dac846f0372bcd51 Mon Sep 17 00:00:00 2001
From: schefner <nick.schefner@ufz.de>
Date: Thu, 16 Jul 2026 13:49:12 +0200
Subject: [PATCH] helmholtz documentation

---
 docs/backends/helmholtz.rst | 80 +++++++++++++++++++++++++++++++++++++
 docs/backends/index.rst     |  1 +
 2 files changed, 81 insertions(+)
 create mode 100644 docs/backends/helmholtz.rst

diff --git a/docs/backends/helmholtz.rst b/docs/backends/helmholtz.rst
new file mode 100644
index 00000000..533f0918
--- /dev/null
+++ b/docs/backends/helmholtz.rst
@@ -0,0 +1,80 @@
+Helmholtz AAI (OpenID Connect)
+==============================
+
+Backend class
+-------------
+
+For Django, add this class path to ``AUTHENTICATION_BACKENDS``. For other
+integrations, use the same class path in the framework-specific backend
+setting.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Backend name
+     - Class path
+   * - ``helmholtz``
+     - ``social_core.backends.helmholtz.HelmholtzOpenIdConnect``
+
+The Helmholtz backend allows authentication against the `Helmholtz AAI`_,
+the authentication and authorization infrastructure of the Helmholtz
+Association operated by HIFIS_.
+
+To obtain a client id and secret, and for the requested scopes to be
+released, you have to register your service with the OP. See the
+`Helmholtz AAI documentation`_ for details.
+
+A minimum configuration is::
+
+    SOCIAL_AUTH_HELMHOLTZ_KEY = '<client_id>'
+    SOCIAL_AUTH_HELMHOLTZ_SECRET = '<client_secret>'
+
+The remaining configuration is auto-detected by fetching::
+
+    https://login.helmholtz.de/oauth2/.well-known/openid-configuration
+
+Username
+--------
+
+The backend reads the username from the ``preferred_username`` claim
+returned by the server. If the username is under a different key, this can
+be overridden::
+
+    SOCIAL_AUTH_HELMHOLTZ_USERNAME_KEY = 'nickname'
+
+This setting indicates that the username should be populated from the
+``nickname`` claim instead.
+
+Scopes
+------
+
+By default the backend requests, besides ``openid``, ``profile`` and
+``email``, the scopes ``voperson_id``, ``eduperson_entitlement``,
+``eduperson_scoped_affiliation``, ``voperson_external_affiliation``,
+``eduperson_assurance`` and ``orcid``. You can request additional scopes,
+for example::
+
+    SOCIAL_AUTH_HELMHOLTZ_SCOPE = ['display_name']
+
+Restricting access by entitlement
+---------------------------------
+
+Access to the service can be restricted to users holding certain
+entitlements (typically representing membership in a virtual
+organization)::
+
+    SOCIAL_AUTH_HELMHOLTZ_ALLOWED_ENTITLEMENTS = [
+        'urn:geant:helmholtz.de:group:my-vo#login.helmholtz.de',
+    ]
+
+A user holding any of the listed entitlements is allowed to log in. If the
+list is empty (the default), all users are allowed.
+
+The entitlements are read from the ``eduperson_entitlement`` claim. If your
+deployment provides them under a different claim, this can be overridden::
+
+    SOCIAL_AUTH_HELMHOLTZ_ENTITLEMENT_KEY = 'entitlement'
+
+.. _Helmholtz AAI: https://hifis.net/aai/
+.. _HIFIS: https://hifis.net
+.. _Helmholtz AAI documentation: https://hifis.net/doc/helmholtz-aai/
diff --git a/docs/backends/index.rst b/docs/backends/index.rst
index d20e356f..19b6bdff 100644
--- a/docs/backends/index.rst
+++ b/docs/backends/index.rst
@@ -93,6 +93,7 @@ Social backends
    gitea
    google
    grafana
+   helmholtz
    instagram
    justgiving
    kakao