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]