From 6bbc35249b6bb9f20bd1ee718515b6fd6695a328 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Mon, 5 Oct 2026 08:56:47 +0200 Subject: [PATCH] docs: document stable identifier migrations Explain the new stable identifiers, legacy migration behavior, and association-only restrictions so deployments can assess upgrade behavior and configure overrides safely. --- docs/backends/arcgis.rst | 4 ++++ docs/backends/cas.rst | 7 +++++++ docs/backends/cognito.rst | 4 ++++ docs/backends/dailymotion.rst | 4 ++++ docs/backends/google.rst | 14 ++++++++++++-- docs/backends/keycloak.rst | 10 +++++++--- docs/backends/lastfm.rst | 5 +++++ docs/backends/mailru.rst | 5 +++++ docs/backends/mixcloud.rst | 7 ++++++- docs/backends/okta.rst | 10 ++++++++++ docs/backends/qiita.rst | 7 ++++--- docs/backends/suse.rst | 4 ++++ docs/backends/trello.rst | 4 ++++ docs/configuration/settings.rst | 10 ++++++---- docs/security.rst | 11 ++++++----- 15 files changed, 88 insertions(+), 18 deletions(-) diff --git a/docs/backends/arcgis.rst b/docs/backends/arcgis.rst index b55cc00f..da186770 100644 --- a/docs/backends/arcgis.rst +++ b/docs/backends/arcgis.rst @@ -18,6 +18,10 @@ setting. ArcGIS uses OAuth2 for authentication. +Accounts are associated by the provider's stable user ``id``. Associations +created by older social-core releases used ``username`` and migrate on the next +successful authentication. + - Register a new application at `ArcGIS Developer Center`_. diff --git a/docs/backends/cas.rst b/docs/backends/cas.rst index c0e60479..48f7f5b0 100644 --- a/docs/backends/cas.rst +++ b/docs/backends/cas.rst @@ -32,6 +32,13 @@ This class functions identically to the generic OIDC backend, but hides the differences in implementation details of the OIDC implementation in Apereo CAS. +User identification +------------------- + +Accounts are associated by the OpenID Connect ``sub`` claim. Associations +created by older social-core releases used the normalized username and migrate +on the next successful authentication. + Note that despite the naming of the backend, this is NOT an implementation of the CAS protocol, also supported by Apereo CAS. The CAS backend is only intended as a way to use the Apereo CAS identity provider as an diff --git a/docs/backends/cognito.rst b/docs/backends/cognito.rst index b01efed6..58fd7d14 100644 --- a/docs/backends/cognito.rst +++ b/docs/backends/cognito.rst @@ -19,6 +19,10 @@ setting. Cognito implemented OAuth2 protocol for their authentication mechanism. To enable ``python-social-auth`` support follow this steps: +Accounts are associated by the immutable ``sub`` claim. Associations created +by older social-core releases used ``username`` and migrate on the next +successful authentication. + 1. Go to `AWS Cognito Console`_ and select ``Manage User Pools``. 2. Choose an existing pool or create a new one following the `Cognito Pool diff --git a/docs/backends/dailymotion.rst b/docs/backends/dailymotion.rst index aec0e7ae..c4e6ad38 100644 --- a/docs/backends/dailymotion.rst +++ b/docs/backends/dailymotion.rst @@ -18,6 +18,10 @@ setting. DailyMotion uses OAuth2. In order to enable the backend follow: +Accounts are associated by the stable provider ``id``. Associations created by +older social-core releases used the renameable screen name and migrate on the +next successful authentication. + - Register an application at `DailyMotion Developer Portal`_ - Fill in the **Client Id** and **Client Secret** values in your settings:: diff --git a/docs/backends/google.rst b/docs/backends/google.rst index 25d1c875..7e1caca9 100644 --- a/docs/backends/google.rst +++ b/docs/backends/google.rst @@ -152,8 +152,13 @@ As of September 30, 2014, Orkut has been `shut down`_. User identification ------------------- -Optional support for static and unique Google Profile ID identifiers instead of -using the e-mail address for account association can be enabled with:: +Google OAuth2, OpenID Connect, and One Tap use the stable ``sub`` claim for +account association. The legacy OAuth1 backend uses Google's stable ``id``. +Associations created by older social-core releases used the email address and +migrate to the stable identifier on the next successful authentication. + +The following legacy settings remain accepted, but stable identifiers are now +the default:: SOCIAL_AUTH_GOOGLE_OAUTH_USE_UNIQUE_USER_ID = True @@ -163,6 +168,11 @@ or:: depending on the backends in use. +See `Configurable User ID Key`_ for migration controls and custom identifier +settings. + +.. _Configurable User ID Key: ../configuration/settings.html#configurable-user-id-key + Refresh Tokens -------------- diff --git a/docs/backends/keycloak.rst b/docs/backends/keycloak.rst index 37f1ab09..5f1923ab 100644 --- a/docs/backends/keycloak.rst +++ b/docs/backends/keycloak.rst @@ -118,10 +118,14 @@ by setting:: This can be useful if you want to use email, username, or another field as the unique identifier instead of the ``sub`` field. +Associations created by older social-core releases used the normalized +``preferred_username`` value and migrate to ``sub`` on the next successful +authentication. + .. warning:: - Changing the ID key after users have already authenticated will prevent them from - logging in, as their stored ``uid`` will not match the new identifier. Configure - this setting before users start authenticating, or perform a data migration. + Usernames and email addresses can change or be reassigned. Selecting one as + ``ID_KEY`` can allow a different provider account to match a stale local + association. See the `Configurable User ID Key`_ documentation for more information about this feature. diff --git a/docs/backends/lastfm.rst b/docs/backends/lastfm.rst index 917cb7f5..ffb44d0f 100644 --- a/docs/backends/lastfm.rst +++ b/docs/backends/lastfm.rst @@ -29,4 +29,9 @@ order to enable the support for it just: - Enable the backend in ``AUTHENTICATION_BACKENDS`` setting. +Last.fm does not expose a stable account identifier in its authentication +session response. The backend is therefore association-only: an authenticated +local user must initiate and complete the connection. Last.fm cannot create a +local user or authenticate a logged-out user. + .. _Get an API Account: http://www.last.fm/api/account/create diff --git a/docs/backends/mailru.rst b/docs/backends/mailru.rst index 12c30f76..fb07104f 100644 --- a/docs/backends/mailru.rst +++ b/docs/backends/mailru.rst @@ -26,6 +26,11 @@ Mail.ru uses OAuth2 workflow. `Register new application`_ to use it and fill in Add ``social_core.backends.mailru.MRGOAuth2`` to ``AUTHENTICATION_BACKENDS`` to activate Mail.ru authorization. +The ``mailru`` backend identifies users by the stable ``id`` returned by the +userinfo endpoint. Associations created by older social-core releases used the +email address and migrate on the next successful authentication. The legacy +``mailru-oauth2`` backend already uses its stable ``uid`` field. + Legacy OAuth2 authorization --------------------------- diff --git a/docs/backends/mixcloud.rst b/docs/backends/mixcloud.rst index a9c60aa0..d5019cd6 100644 --- a/docs/backends/mixcloud.rst +++ b/docs/backends/mixcloud.rst @@ -16,7 +16,7 @@ setting. * - ``mixcloud`` - ``social_core.backends.mixcloud.MixcloudOAuth2`` -The `Mixcloud API`_ offers support for authorization. To this backend support: +The `Mixcloud API`_ offers support for authorization. To enable this backend: - Register a new application at `Mixcloud Developers`_ @@ -42,5 +42,10 @@ The `Mixcloud API`_ offers support for authorization. To this backend support: as a list of tuples ``(response name, alias)`` to store user profile data on the ``UserSocialAuth.extra_data``. +Mixcloud does not expose a documented stable account identifier. The backend is +association-only: an authenticated local user must initiate and complete the +connection. Mixcloud cannot create a local user or authenticate a logged-out +user. + .. _Mixcloud API: http://www.mixcloud.com/developers/documentation .. _Mixcloud Developers: http://www.mixcloud.com/developers diff --git a/docs/backends/okta.rst b/docs/backends/okta.rst index b142918c..faabf3a2 100644 --- a/docs/backends/okta.rst +++ b/docs/backends/okta.rst @@ -69,3 +69,13 @@ https://dev-123456.okta.com/oauth2)`` settings with the values from the IdP setu SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = '' SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = '' SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = '' + +User identification +------------------- + +Both Okta backends identify users by the stable ``sub`` claim. Associations +created by older social-core releases used ``preferred_username`` and migrate +to ``sub`` on the next successful authentication. See `Configurable User ID +Key`_ for migration controls and custom identifier settings. + +.. _Configurable User ID Key: ../configuration/settings.html#configurable-user-id-key diff --git a/docs/backends/qiita.rst b/docs/backends/qiita.rst index a28af596..d11c04d1 100644 --- a/docs/backends/qiita.rst +++ b/docs/backends/qiita.rst @@ -33,9 +33,10 @@ Qiita See auth scopes at `Qiita Scopes docs`_. -- Default behavior is to identify users by their `id`. However, this can be changed by renaming accounts, etc. - - If you want to identify each user with a unique `permanent_id`, set the following:: +- Users are identified by the stable ``permanent_id``. Associations created by + older social-core releases used the renameable ``id`` and migrate on the next + successful authentication. The following legacy setting remains accepted, + but no longer changes the default:: SOCIAL_AUTH_QIITA_IDENTIFIED_BY_PERMANENT_ID = True diff --git a/docs/backends/suse.rst b/docs/backends/suse.rst index 06707d5f..0df87ea8 100644 --- a/docs/backends/suse.rst +++ b/docs/backends/suse.rst @@ -25,4 +25,8 @@ openSUSE OpenID openSUSE OpenID works straightforward, not settings are needed. Domains or emails whitelists can be applied too, check the whitelists_ settings for details. +The backend uses the verified OpenID identity URL for account association. +Associations created by older social-core releases used ``nickname`` and +migrate on the next successful authentication. + .. _whitelists: ../configuration/settings.html#whitelists diff --git a/docs/backends/trello.rst b/docs/backends/trello.rst index 8ea46c2a..7f43bc33 100644 --- a/docs/backends/trello.rst +++ b/docs/backends/trello.rst @@ -18,6 +18,10 @@ setting. Trello provides OAuth1 support for their authentication process. +Accounts are associated by Trello's stable member ``id``. Associations created +by older social-core releases used ``username`` and migrate on the next +successful authentication. + In order to enable it, follow: - Generate an Application Key pair at `Trello Developers API Keys`_ diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst index 13418fa2..144fcf29 100644 --- a/docs/configuration/settings.rst +++ b/docs/configuration/settings.rst @@ -276,10 +276,12 @@ an Azure AD backend:: SOCIAL_AUTH_AZUREAD_V2_TENANT_OAUTH2_ID_KEY = 'sub' The generic OpenID backend and Steam derive the identifier from the asserted -OpenID identity URL, so ``ID_KEY`` does not apply to them. The SAML backend -uses the per-IdP ``attr_user_permanent_id`` mapping instead. See the -:doc:`OpenID <../backends/openid>`, :doc:`Steam <../backends/steam>`, and -:doc:`SAML <../backends/saml>` backend documentation. +OpenID identity URL, so ``ID_KEY`` does not apply to them. The Ubuntu, +openSUSE, and Yandex OpenID backends expose that protocol identifier as +``identity_url`` and allow an explicit override. The SAML backend uses the +per-IdP ``attr_user_permanent_id`` mapping instead. See the :doc:`OpenID +<../backends/openid>`, :doc:`Steam <../backends/steam>`, and :doc:`SAML +<../backends/saml>` backend documentation. Associations store both the identifier value and the name of the provider field that supplied it. When a bundled backend changes to a more stable default, diff --git a/docs/security.rst b/docs/security.rst index 19c6a7cd..06d91316 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -9,11 +9,12 @@ must therefore come from a provider identifier that is immutable and cannot be reassigned, rather than a display name, email address, UPN, or other human-readable login name. -Bundled backends use stable provider identifiers where available. Tumblr uses -the primary blog UUID, Deezer its numeric account ID, Discourse -``external_id``, SciStarter ``profile_id``, and Microsoft Entra ID/Azure AD -backends ``sub``. Applications overriding a backend's ``ID_KEY`` are -responsible for ensuring the selected claim has the same stability properties. +Bundled backends use stable provider identifiers where available, including +OIDC ``sub`` claims, provider account IDs, UUIDs, and verified OpenID identity +URLs. Applications overriding a backend's ``ID_KEY`` are responsible for +ensuring the selected claim has the same stability properties. Backends whose +provider responses expose no stable identifier, including Drip, Last.fm, and +Mixcloud, are association-only and require an authenticated local user. When upgrading an existing deployment, read :ref:`the configurable user ID key documentation ` before authenticating users. The