



Network Working Group                                   S. Bou Aram, Ed.
Internet-Draft                                               August 2025
Intended status: Informational                                          
Expires: 9 February 2026


             OpenID Connect Email Account Linking Extension
             draft-bouaram-oidc-email-linking-extension-00

Abstract

   This document extends OpenID Connect's standard email functionality
   to support secure linking between multiple email accounts.  It
   enables users to associate secondary email addresses with their
   primary account while maintaining backward compatibility with
   existing implementations.  The extension provides methods for
   establishing, managing, and utilizing these relationships within the
   OpenID Connect email scope.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 2 February 2026.

Copyright Notice

   Copyright (c) 2025 IETF Trust and the persons identified as the
   document authors.  All rights reserved.











Bou Aram                 Expires 9 February 2026                [Page 1]

Internet-Draft             OIDC Email Linking                August 2025


   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Core Concepts . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Protocol Parameters . . . . . . . . . . . . . . . . . . . . .   2
   3.  Protocol Flows  . . . . . . . . . . . . . . . . . . . . . . .   3
     3.1.  Linking Flow  . . . . . . . . . . . . . . . . . . . . . .   3
     3.2.  Unlinking Flow  . . . . . . . . . . . . . . . . . . . . .   4
     3.3.  Secondary Account Authentication  . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

1.  Core Concepts

   The extension operates on these fundamental principles:

   1.  *Primary Account*: The initial identity that controls all linked
       accounts

   2.  *Secondary Accounts*: Additional email identities linked to the
       primary

   3.  *Temporal Validity*: Linkages expire after a defined period

   4.  *Account Resolution*: Secondary logins resolve to the primary
       identity

2.  Protocol Parameters

   +================+===============+=================================+
   | Parameter      | Location      | Description                     |
   +================+===============+=================================+
   | linking        | Authorization | boolean (true/false), initiates |
   |                | Request       | linking flow when true          |
   +----------------+---------------+---------------------------------+
   | linking_period | Authorization | number (seconds), validity      |
   |                | Request       | duration (default: 2592000)     |
   +----------------+---------------+---------------------------------+




Bou Aram                 Expires 9 February 2026                [Page 2]

Internet-Draft             OIDC Email Linking                August 2025


                           Table 1: Parameters

3.  Protocol Flows

3.1.  Linking Flow

   Complete sequence for establishing account linkages:

   +----------+       +----------+       +----------+
   |  Client  |       |  IdP/STS  |      |   User   |
   +----------+       +----------+       +----------+
        | Auth Request      |                  |
        | scope=email       |                  |
        | linking=true      |                  |
        |------------------>|                  |
        |                  | Primary Auth      |
        |                  |------------------>|
        |                  |                   |
        |                  | Show Linking      |
        |                  | Consent Screen    |
        |                  | (where user adds  |
        |                  |  or               |
        |                  | selects email     |
        |                  | accounts)         |
        |                  |------------------>|
        |                  | (1-N secondary    |
        |                  |  accounts based   |
        |                  |  on IdP policy    |
        |                  | and allowed N     |
        |                  | Secondaries)      |
        |                  |<------------------|
        |                  |   Auth Secondary 1|
        |                  |<----------------- |
        |                  |  Auth Secondary N |
        |                  |<------------------|
        |                  |                   |
        |           IDP/STS stores Linkages    |
        |                  |                   |
        | ID Token with    |                   |
        | linking claims:  |                   |
        | - primary_email  |                   |
        | - secondary_emails[N] |              |
        | - expires_at     |                   |
        |<-----------------|                   |

   1.  Client initiates with parameters:





Bou Aram                 Expires 9 February 2026                [Page 3]

Internet-Draft             OIDC Email Linking                August 2025


   GET /authorize?response_type=code
     &client_id=client123
     &scope=openid%20email
     &linking=true
     &linking_period=604800

   2.  IdP authenticates primary account, the account should be primary
   or normal (not linked) email account

   3.  User authenticates 1-N secondary accounts (IdP-defined limit)

   4.  IdP stores linkages with desired expiration timestamp

   5.  IdP returns ID token containing:

   {
     "email": "main@example.com",
     "primary": true,
     "linking": {
       "secondary_emails": ["alt1@example.com", "alt2@example.org"],
       "expires_at": 1735689600
     }
   }

3.2.  Unlinking Flow

   Unlinking occurs through the standard linking interface when
   initiated by primary accounts:























Bou Aram                 Expires 9 February 2026                [Page 4]

Internet-Draft             OIDC Email Linking                August 2025


   +----------+       +----------+       +----------+
   |  Client  |       |  IdP/STS |       |   User   |
   +----------+       +----------+       +----------+
        | Auth Request      |                  |
        | scope=email       |                  |
        | linking=true      |                  |
        |------------------>|                  |
        |                  | Primary Auth      |
        |                  |------------------>|
        |                  |                   |
        |                  | Show Linking      |
        |                  | Consent Screen    |
        |                  | with "Unlink All" |
        |                  | option only       |
        |                  |------------------>|
        |                  | User confirms     |
        |                  | "Unlink All"      |
        |                  |<------------------|
        |                  |                   |
        | ID Token with    |                   |
        | standard claims  |                   |
        |<------------------|                  |

   1.  User authenticates with primary account credentials

   2.  IdP displays linking consent screen with:

   *  List of currently linked accounts

   *  Single "Unlink All" option

   *  No account selection options

   3.  User confirms by clicking "Unlink All"

   4.  IdP completely removes all linkages

   5.  Standard ID token returned with empty linkage:

   {
     "email": "main@example.com",
     "linking": {}
   }

3.3.  Secondary Account Authentication

   When authenticating with an email account that is linked to a primary
   account:



Bou Aram                 Expires 9 February 2026                [Page 5]

Internet-Draft             OIDC Email Linking                August 2025


   1.  Client initiates standard OIDC authentication:

   GET /authorize?response_type=code
     &client_id=client123
     &scope=openid%20email

   2.  IdP/STS performs normal authentication flow

   3.  After successful authentication, system checks for account
   linkages

   4.  For secondary accounts, ID token contains:

   {
     "email": "secondary@example.com",
     "linking": {
       "is_primary": false,
       "primary_email": "main@example.com",
       "expires_at": 1735689600
     }
   }

   Applications must process the token as follows:

   *  Use primary_email as the canonical user identifier

   *  Verify expires_at is in the future

   *  Treat permissions/access identical to primary account login

   *  Include secondary email in audit logs only

4.  Security Considerations

   Key security requirements:

   1.  *Authentication Requirements*:

       *  All accounts must complete full authentication during linking

       *  Secondary accounts cannot initiate linking/unlinking

   2.  *Token Validation*:

       *  Linking expiry must always be validated

   3.  *Account Resolution*:




Bou Aram                 Expires 9 February 2026                [Page 6]

Internet-Draft             OIDC Email Linking                August 2025


       *  Always resolve secondary logins to primary email account

   4.  *Audit Logging*:

       *  Log all linking/unlinking events

       *  Record both primary and secondary emails in logs

5.  IANA Considerations

   This document has no IANA actions.

Author's Address

   Salim BOU ARAM (editor)
   Beirut
   Lebanon
   Email: salimbouaram12@gmail.com

































Bou Aram                 Expires 9 February 2026                [Page 7]
