<a id="identifier-migration"></a>

<a id="id1"></a>

# Identifier migration

Authentication looks up the current `(provider, id_key, uid)` first. If it
does not exist, it looks up previous keys and their values from the authenticated
provider response. These queries use the existing provider/UID index; they do
not search every association’s JSON data. Empty-key historical rows are also
considered using the same indexed UID lookups.

An old email or username locates a candidate, but does not prove that the
candidate belongs to the current provider account. The candidate’s saved current
identifier must match the authenticated identifier. Multiple candidates,
conflicting evidence, and invalid evidence stop authentication. Missing evidence
also stops authentication unless the compatibility policy below permits it.
Migration updates both identifier fields atomically and revalidates evidence
under the association lock.

<a id="configuration-changes"></a>

## Configuration changes

Before switching identifiers, configure extra data to save the proposed new
stable field while the old key is still active. Existing users must authenticate
in this configuration, or receive an independently verified administrative
backfill, before their associations contain that evidence. Adding an extra-data
setting does not populate historical rows automatically.

For example, while Google still uses email:

```default
SOCIAL_AUTH_GOOGLE_OAUTH2_ID_KEY = "email"
SOCIAL_AUTH_GOOGLE_OAUTH2_EXTRA_DATA = [("sub", "sub")]
```

Then switch the active key and retain the historical key:

```default
SOCIAL_AUTH_GOOGLE_OAUTH2_ID_KEY = "sub"
SOCIAL_AUTH_GOOGLE_OAUTH2_LEGACY_ID_KEYS = ["email"]
SOCIAL_AUTH_GOOGLE_OAUTH2_ALLOW_UNVERIFIED_LEGACY_UID_MIGRATION = False
```

Configured historical keys supplement the backend’s built-in keys, and work
with an explicit current `ID_KEY`. Custom backends must implement extraction
for their historical keys when identifiers require transformations or scoping.

If an email or username has changed and its old value is no longer returned,
indexed lookup cannot recover the old association. There is no global JSON
search fallback. Use account recovery or an authenticated linking flow.
Presenting a reclaimed mutable identifier with conflicting stored evidence
always fails, including when unverified migration is enabled.

<a id="compatibility-policy"></a>

## Compatibility policy

`ALLOW_UNVERIFIED_LEGACY_UID_MIGRATION` defaults to enabled only for the
specific built-in transitions marked “Yes” below. It requires the audited
backend class and current built-in key. Custom subclasses, newly added legacy
keys, and other configuration-driven transitions require evidence by default.
When `ID_KEY` is configured, a match through the historical key requires
evidence even if the configured value equals the current built-in default.
Pre-6.0 associations may already hold that configured identifier, despite
having an empty stored `id_key`. A login with the same current UID can still
stamp the key without changing account ownership. Other current keys also
require evidence.

The global `SOCIAL_AUTH_ALLOW_UNVERIFIED_LEGACY_UID_MIGRATION` setting and its
backend-specific variants override that default. Explicit `False` always
requires evidence. Explicit `True` permits missing evidence even outside the
audited list, but cannot override conflicting or invalid evidence.

Values returned only by the compatibility `get_legacy_user_ids` hook have no
identifier-key provenance. Policy hooks receive an empty old key for them. When
`ID_KEY` is configured, these matches require stored evidence unless
`ALLOW_UNVERIFIED_LEGACY_UID_MIGRATION` is explicitly `True` and the policy
hook also approves the empty key.

#### WARNING
Allowing missing evidence accepts the risk that a new owner of an old email,
username, or other mutable identifier can claim its association. The
compatibility policy preserves that behavior for known historical setups;
it does not make those migrations safe. Disable it before upgrading if this
risk is unacceptable.

If you selected a stable `ID_KEY` before upgrading from social-core 5.x,
retain that setting until all older associations have been keyed correctly.
Removing it can make an unkeyed association indistinguishable from one created
under the historical identifier. An attacker whose historical identifier equals
another account’s stable ID could then claim that account. Audit and repair
existing associations using independently verified provider identifiers before
removing the setting. Do not infer a row’s original key from its UID alone.

For Django, set `SOCIAL_AUTH_OLD_ID_KEYS` to the identifiers that actually
created your associations before running the historical-key backfill migration.
Its built-in defaults describe the old backend defaults, not custom settings.
If the migration has already labeled rows with the wrong key, audit and correct
those rows using trusted records; changing the setting afterwards does not
repair persisted `id_key` values.

<a id="historical-identifier-audit"></a>

<a id="historical-backend-audit"></a>

## Historical backend audit

This table describes default storage declarations in social-core 5.2.0 for the
25 built-in backend variants that now declare historical identifier keys.
Three stored the new identifier directly; Fence and CAS stored `sub` under
`id`. The remaining 20 lacked a directly usable stable identifier field.
Stored ID tokens are not decoded as migration evidence. Actual data can differ
because of older releases, custom pipelines, or extra-data configuration.

#### Historical transitions and default compatibility allowances

| Provider                   | Old key              | Current key    | Stored evidence   | Unverified default   |
|----------------------------|----------------------|----------------|-------------------|----------------------|
| `arcgis`                   | `username`           | `id`           | Absent            | Yes                  |
| `azuread-oauth2`           | `upn`                | `sub`          | Absent            | Yes                  |
| `azuread-oauth2-v2`        | `upn`                | `sub`          | Absent            | Yes                  |
| `azuread-v2-tenant-oauth2` | `preferred_username` | `sub`          | Absent            | Yes                  |
| `cas`                      | `username`           | `sub`          | Alias `id`        | No                   |
| `cognito`                  | `username`           | `sub`          | Absent            | Yes                  |
| `dailymotion`              | `username`           | `id`           | `id`              | No                   |
| `deezer`                   | `name`               | `id`           | Absent            | Yes                  |
| `discourse`                | `email`              | `external_id`  | Absent            | Yes                  |
| `fence`                    | `username`           | `sub`          | Alias `id`        | No                   |
| `google-oauth`             | `email`              | `id`           | Absent            | Yes                  |
| `google-oauth2`            | `email`              | `sub`          | Absent            | Yes                  |
| `google-onetap`            | `email`              | `sub`          | Absent            | Yes                  |
| `google-openidconnect`     | `email`              | `sub`          | Absent            | Yes                  |
| `keycloak`                 | `username`           | `sub`          | Absent            | Yes                  |
| `mailru`                   | `email`              | `id`           | Absent            | Yes                  |
| `okta-oauth2`              | `preferred_username` | `sub`          | Absent            | Yes                  |
| `okta-openidconnect`       | `preferred_username` | `sub`          | Absent            | Yes                  |
| `opensuse`                 | `nickname`           | `identity_url` | Absent            | Yes                  |
| `qiita`                    | `id`                 | `permanent_id` | `permanent_id`    | No                   |
| `scistarter`               | `email`              | `profile_id`   | `profile_id`      | No                   |
| `trello`                   | `username`           | `id`           | Absent            | Yes                  |
| `tumblr`                   | `name`               | `uuid`         | Absent            | Yes                  |
| `ubuntu`                   | `nickname`           | `identity_url` | Absent            | Yes                  |
| `yandex-openid`            | `email`              | `identity_url` | Absent            | Yes                  |

<a id="django-historical-backfill"></a>

## Django historical backfill

The Django data migration records historical keys using frozen pre-v7 defaults.
It changes neither UIDs nor account ownership. Configure
`SOCIAL_AUTH_OLD_ID_KEYS` before running it if previous settings selected a
different identifier. This includes Google `USE_UNIQUE_USER_ID` and Qiita
`IDENTIFIED_BY_PERMANENT_ID`. For example:

```default
SOCIAL_AUTH_OLD_ID_KEYS = {
    "google-oauth2": "sub",
    "qiita": "permanent_id",
    "custom-provider": "old_subject",
    "trello": None,
}
```

Unknown and skipped providers retain empty keys. Authentication considers them
only through indexed UID candidates and the same evidence policy. A historical
key describes how existing associations were created; current settings alone
cannot establish it. See [Django Framework](django.html.md) for deployment order and migration costs.