Content is user-generated and unverified.

OpenID Federation with Decentralized Identifiers

Version: 1.0
Date: September 2025
Authors: [To be filled]

Abstract

This specification defines how OpenID Federation Entity Configuration discovery can be enhanced through the use of Decentralized Identifiers (DIDs). It extends the OpenID Federation specification to allow DID documents to serve as alternative discovery mechanisms for OpenID Federation Entity Identifiers, enabling decentralized discovery of federation participants while maintaining compatibility with existing OpenID Federation trust mechanisms.

1. Introduction

OpenID Federation provides a mechanism for establishing trust between OpenID Connect parties through a hierarchical trust model using Entity Statements and Trust Anchors. Decentralized Identifiers (DIDs) offer a decentralized approach to identifier resolution and verification.

This specification defines how DID documents can reference OpenID Federation Entity Identifiers, enabling DID-based discovery of federation entities while preserving the OpenID Federation trust evaluation mechanisms.

1.1 Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.2 Scope

This specification focuses on Entity Configuration discovery through DID documents. It does not:

  • Define new trust evaluation mechanisms beyond those in OpenID Federation
  • Require modifications to Entity Statement processing
  • Mandate specific DID methods
  • Address DID document verification procedures

2. Terminology

DID Subject: The entity identified by the DID, as defined in the DID specification.

OpenID Federation Entity: An entity participating in an OpenID Federation, identified by an Entity Identifier.

Entity Configuration: A JWT containing metadata about an OpenID Federation entity, as defined in the OpenID Federation specification.

Service Map: An entry in the service property of a DID document that describes how to interact with a service associated with the DID subject.

3. DID Document Service Extension

3.1 Service Type Definition

This specification defines a new service type OpenIDFederation for inclusion in DID documents.

3.2 Service Properties

A service entry of type OpenIDFederation MUST include the following properties:

  • id: A URI that uniquely identifies the service within the DID document
  • type: MUST be set to "OpenIDFederation"
  • serviceEndpoint: The OpenID Federation Entity Identifier URI
  • role: OPTIONAL. Specifies the role of the referenced entity

3.2.1 Role Property Values

(Normative)

The role property, when present, MUST contain one of the following values:

  • "subject": Indicates the Entity Identifier belongs to the DID subject itself
  • "trust_anchor": Indicates the Entity Identifier belongs to a Trust Anchor

If the role property is omitted, implementations SHOULD treat the service as referring to the DID subject.

3.3 Example DID Document

(Informative)

json
{
  "@context": [
    "https://www.w3.org/ns/did/v1"
  ],
  "id": "did:example:123456789abcdefghi",
  "service": [
    {
      "id": "did:example:123456789abcdefghi#openid-federation-subject",
      "type": "OpenIDFederation",
      "serviceEndpoint": "https://issuer.example.com",
      "role": "subject"
    },
    {
      "id": "did:example:123456789abcdefghi#openid-federation-ta",
      "type": "OpenIDFederation", 
      "serviceEndpoint": "https://ta.federation.example.org",
      "role": "trust_anchor"
    }
  ]
}

4. Discovery Process

4.1 DID-based Entity Configuration Discovery

(Normative)

When an OpenID Federation participant receives a DID as an identifier for an entity, it MAY use the following process to discover the entity's OpenID Federation Entity Configuration:

  1. Resolve the DID to obtain the DID document
  2. Locate service entries with type set to "OpenIDFederation"
  3. For services with role set to "subject" (or no role specified), use the serviceEndpoint as the Entity Identifier
  4. Retrieve the Entity Configuration from the well-known endpoint of the Entity Identifier

4.2 Process Flow

(Informative)

┌─────────────┐    1. DID Resolution    ┌──────────────┐
│   Client    │ ────────────────────────▶│ DID Registry │
│             │                         │   (varies)   │
└─────────────┘                         └──────────────┘
       │                                        │
       │              2. DID Document           │
       │ ◀──────────────────────────────────────┘
       │
       │ 3. Extract OpenIDFederation services
       │ 4. Identify Entity Identifier(s)
       │
       │    5. GET /.well-known/openid_federation
       └────────────────────────────────────────┐
                                                │
┌───────────────────────────────────────────────▼──┐
│         OpenID Federation Entity              │
│                                               │
│  /.well-known/openid_federation               │
│  └─▶ Entity Configuration (JWT)               │
└───────────────────────────────────────────────────┘

4.3 HTTP Interactions

(Informative)

4.3.1 Entity Configuration Retrieval

After extracting the Entity Identifier from the DID document service entry:

Request:

http
GET /.well-known/openid_federation HTTP/1.1
Host: issuer.example.com
Accept: application/entity-statement+jwt

Response:

http
HTTP/1.1 200 OK
Content-Type: application/entity-statement+jwt
Cache-Control: max-age=3600

eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFt...

5. Trust Anchor Discovery

5.1 Trust Anchor Reference

(Normative)

DID documents MAY include service entries with role set to "trust_anchor" to provide hints about relevant Trust Anchors for the DID subject's federation participation.

5.2 Trust Anchor Processing

(Normative)

When processing Trust Anchor references from DID documents:

  1. Clients MUST validate that the referenced Trust Anchor is acceptable according to their local policy
  2. Clients MUST NOT automatically trust an entity solely based on Trust Anchor references in DID documents
  3. The normal OpenID Federation trust evaluation process MUST be followed

5.3 Multiple Trust Anchors

(Informative)

A DID document may reference multiple Trust Anchors to indicate the DID subject's participation in multiple federations:

json
{
  "id": "did:example:123456789abcdefghi",
  "service": [
    {
      "id": "did:example:123456789abcdefghi#federation-subject",
      "type": "OpenIDFederation",
      "serviceEndpoint": "https://issuer.example.com",
      "role": "subject"
    },
    {
      "id": "did:example:123456789abcdefghi#ta-health",
      "type": "OpenIDFederation",
      "serviceEndpoint": "https://health.ta.example.org",
      "role": "trust_anchor"
    },
    {
      "id": "did:example:123456789abcdefghi#ta-education", 
      "type": "OpenIDFederation",
      "serviceEndpoint": "https://education.ta.example.org",
      "role": "trust_anchor"
    }
  ]
}

6. Implementation Considerations

6.1 Fallback Mechanisms

(Normative)

Implementations SHOULD provide fallback mechanisms when DID resolution fails or when DID documents do not contain OpenIDFederation service entries.

6.2 Caching

(Informative)

Implementations MAY cache resolved DID documents according to the caching policies of the DID method used. Care should be taken to respect both DID method-specific caching rules and OpenID Federation Entity Configuration caching requirements.

6.3 Error Handling

(Normative)

When DID resolution fails or returns invalid documents, implementations MUST handle errors gracefully and MAY attempt alternative discovery methods.

7. Security Considerations

7.1 DID Document Integrity

(Informative)

This specification relies on the security properties of the underlying DID method for ensuring DID document integrity. Implementations should be aware that compromised DID documents could redirect Entity Configuration discovery to malicious endpoints.

7.2 Entity Impersonation

(Informative)

The use of DIDs for Entity Configuration discovery introduces potential attack vectors where malicious actors might:

  • Create DIDs that reference legitimate Entity Identifiers without authorization
  • Modify DID documents to point to malicious Entity Configurations
  • Use DID methods with weak security properties

Implementations should validate that the DID subject has legitimate authority to reference the claimed Entity Identifiers.

7.3 Privacy Considerations

(Informative)

Since this specification primarily targets organizational entities (issuers and verifiers) rather than natural persons, privacy implications are generally limited. However, implementations should consider:

  • Whether DID resolution creates unintended correlation opportunities
  • The public nature of most DID methods and their implications for organizational privacy
  • Potential inference attacks based on Trust Anchor associations

7.4 Trust Boundary Considerations

(Normative)

The security of the overall system depends on both the DID method's security properties and the OpenID Federation trust mechanisms. Implementations MUST NOT consider an entity trusted solely because it is referenced in a DID document. The complete OpenID Federation trust evaluation process MUST be performed.

8. IANA Considerations

8.1 DID Service Type Registration

This specification requests registration of the service type OpenIDFederation for use in DID documents.

Service Type: OpenIDFederation
Description: OpenID Federation Entity Identifier reference
Specification: This document

9. References

9.1 Normative References

  • [OpenID Federation] Hedberg, R., Jones, M., Solberg, A., Bradley, J., De Marco, G., and V. Dzhuvinov, "OpenID Federation 1.0", OpenID Foundation, 2024.
  • [DID-CORE] Reed, D., Sporny, M., Longley, D., Sabadello, M., Grant, R., and A. Guy, "Decentralized Identifiers (DIDs) v1.0", W3C Recommendation, 2022.
  • [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017.

9.2 Informative References

  • [OpenID Federation Wallet] "OpenID Federation for Wallet Architectures", OpenID Foundation, 2024.
  • [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.

Appendix A. Complete Example Flow

(Informative)

This appendix provides a complete example of discovering an OpenID Federation Entity Configuration through a DID.

A.1 Scenario

A Relying Party wants to discover the Entity Configuration for an issuer identified by the DID did:web:issuer.example.com.

A.2 Step-by-Step Process

  1. DID Resolution Request:
http
   GET /.well-known/did.json HTTP/1.1
   Host: issuer.example.com
  1. DID Document Response:
json
   {
     "@context": ["https://www.w3.org/ns/did/v1"],
     "id": "did:web:issuer.example.com", 
     "service": [
       {
         "id": "did:web:issuer.example.com#openid-federation",
         "type": "OpenIDFederation",
         "serviceEndpoint": "https://issuer.example.com",
         "role": "subject"
       },
       {
         "id": "did:web:issuer.example.com#trust-anchor",
         "type": "OpenIDFederation", 
         "serviceEndpoint": "https://federation.trust.example.org",
         "role": "trust_anchor"
       }
     ]
   }
  1. Entity Configuration Discovery:
http
   GET /.well-known/openid_federation HTTP/1.1
   Host: issuer.example.com
   Accept: application/entity-statement+jwt
  1. Entity Configuration Response:
http
   HTTP/1.1 200 OK
   Content-Type: application/entity-statement+jwt
   
   eyJhbGciOiJSUzI1NiIsImtpZCI6InNpZ25pbmctMSJ9.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLmNvbSIsInN1YiI6Imh0dHBzOi8vaXNzdWVyLmV4YW1wbGUuY29tIiwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJ1c2UiOiJzaWciLCJraWQiOiJzaWduaW5nLTEiLCJuIjoiLi4uIiwiZSI6IkFRQUIifV19LCJhdXRob3JpdHlfaGludHMiOlsiaHR0cHM6Ly9mZWRlcmF0aW9uLnRydXN0LmV4YW1wbGUub3JnIl0sIm1ldGFkYXRhIjp7Im9wZW5pZF9jcmVkZW50aWFsX2lzc3VlciI6eyJjcmVkZW50aWFsX2lzc3VlciI6Imh0dHBzOi8vaXNzdWVyLmV4YW1wbGUuY29tIiwiY3JlZGVudGlhbF9lbmRwb2ludCI6Imh0dHBzOi8vaXNzdWVyLmV4YW1wbGUuY29tL2NyZWRlbnRpYWwiLCJjcmVkZW50aWFsc19zdXBwb3J0ZWQiOlt7ImZvcm1hdCI6InZjK3NkLWp3dCIsImNyZWRlbnRpYWxfZGVmaW5pdGlvbiI6eyJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiSURDcmVkZW50aWFsIl19fV19fSwiaWF0IjoxNjk0MDk2NDAwLCJleHAiOjE2OTQxODI4MDB9.signature
  1. Normal OpenID Federation Processing Continues: The Relying Party proceeds with standard OpenID Federation trust evaluation using the discovered Entity Configuration and the authority hints contained within it.
Content is user-generated and unverified.
    OpenID Federation with Decentralized Identifiers | Claude