nijel · Oct 5, 2026 · Oct 5, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <configurable-user-id-key>` before authenticating users. The