Automatic Certificate Management Environment (ACME) with OpenID Federation 1.0

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 23 April 2026.¶

Copyright Notice

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

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. Introduction

This document describes extensions to the ACME protocol that integrate with OpenID Federation 1.0, allowing an ACME server to issue X.509 Certificates associated with a given OpenID Federation entity. An entity can be a school, government agency, corporation, automated system, or any participant that wishes to join the Federation.¶

In a multilateral federation, composed of thousands of entities belonging to different organizations, all the participants adhere to the same regulation or trust framework. OpenID Federation 1.0 allows each participant to recognize other participants using a trust evaluation mechanism, with RESTful services and cryptographic materials.¶

Federation members declare what kind Entities they are using a basic OpenID Federation component called an Entity Configuration, a signed JSON Web Token published in a well-known resource. This document defines new OpenID Federation Entity Types for certificate Requestors and Issuers, facilitating automated discovery of an issuer's ACME API.¶

X.509 Certificates can be provided to one or more such entities, without having pre-established any direct relationship or contract.¶

These Certificates are useful for integrating with existing systems and protocols which require X.509 Certificates. For example, RADIUS ([RFC2865]) deployments often require Certificates to authenticate clients, or these Certificates could also be used for TLS [RFC8446]. In order to accommodate a variety of use cases, this document adds no requirement that CAs conform to any particular issuance profile, because fields of the X.509 Certificates like the Common Names, Subject Alternative Names or Key Usages may depend on details of those existing systems.¶

This document extends [RFC5280], ACME ([RFC8555]) and OpenID Federation 1.0 ([OPENID-FED]) in the following ways:¶

• It defines a new ACME Identifier type called openid-federation (Section 4).¶

• It defines a new ACME challenge type called openid-federation-01 (Section 5).¶

• It defines new OpenID Federation 1.0 Entity Types acme_issuer (Section 7.1) and acme_requestor (Section 6).¶

• It defines how OpenID Federation 1.0 Superior Entities can use Subordinate Statements to publish X.509 Certificates previously issued with ACME (Section 8).¶

• It defines a new SubjectAlternativeName type id-on-OpenIdFederationEntityId and a corresponding OID so that OpenID Federation 1.0 Entity Identifiers can be included in X.509 Certificates if an Issuer wishes (Section 9).¶

2. Terminology

The terms "Federation Entity", "Trust Anchor", "Entity Configuration", "Subordinate Statement", "Superior Entity", "Immediate Superior Entity", "Federation Entity Keys", "Federation Entity Discovery", "Trust Mark", "Trust Chain", and "Resolved Metadata" used in this document are defined in Section 1.2 of [OPENID-FED].¶

The term "Certificate Signing Request" (CSR) used in this document is defined as a "Certification Request" in [RFC2986]. The term "Certification Authority" used in this document is defined in [RFC5280]. The terms "ACME Client" and "ACME Server" are defined in [RFC8555].¶

The specification also defines the following terms:¶

ACME Identifier:

An identifier in the sense of [RFC8555]. Some identifier that the ACME client proves control of to the ACME server.¶

Entity Identifier:

A URL that uniquely identifies an Entity in OpenID Federation, as defined in Section 1.2 of [OPENID-FED].¶

Requestor:

A Federation Entity which wants to request X.509 Certificates. It operates a web server for hosting its Entity Configuration. It also operates an ACME client, extended according to this document.¶

Certificate Issuer (or Issuer):

A Federation Entity which issues X.509 Certificates. It operates a web server for hosting its Entity Configuration. It also operates an ACME server, extended according to this document.¶

3. Conventions and Definitions

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.¶

4. OpenID Federation ACME Identifier

This document defines a new ACME Identifier type for OpenID Federation Entities, openid-federation, whose value is the sub parameter of the Requestor's Entity Configuration, as defined in Section 1.2 of [OPENID-FED].¶

For example, the ACME Identifier corresponding to the example Entity Configuration in Section 6 is:¶

{"type": "openid-federation", "value": "https://requestor.example.com"}

The openid-federation ACME Identifier type MUST NOT be validated except by the openid-federation-01 challenge.¶

5. OpenID Federation Challenge Type

The OpenID Federation challenge type allows a Requestor to prove control of a Federation Entity using the trust evaluation mechanism provided by [OPENID-FED]. The Requestor demonstrates control of a cryptographic public key published in its OpenID Federation Entity Configuration.¶

There are two ways the Certificate Issuer is able to check if a Requestor is part of the federation:¶

• The Requestor provides a Trust Chain when solving the ACME challenge. This is RECOMMENDED since it reduces the effort of the Certificate Issuer in evaluating the trust to the Requestor.¶

• The Requestor doesn't provide a Trust Chain in the challenge solution.¶

The openid-federation-01 ACME challenge object has the following format:¶

type (required, string): The string "openid-federation-01"¶

token (required, string): A random value that uniquely identifies the challenge. This value MUST have at least 128 bits of entropy. It MUST NOT contain any characters outside the base64url alphabet as described in Section 5 of [RFC4648]. Trailing '=' padding characters MUST be stripped. See [RFC4086] for additional information on randomness requirements.¶

trustAnchors (optional, array of string): An array of strings containing the Entity Identifiers of the Issuer's Trust Anchors. When solving the challenge, the Requestor can construct a Trust Chain from itself to one of these Trust Anchors. It is RECOMMENDED that the Issuer includes this field to make it easier for the Requestor to construct a Trust Chain.¶

A non-normative example of a challenge with trustAnchors specified:¶

   {
     "type": "openid-federation-01",
     "url": "https://issuer.example.com/acme/chall/prV_B7yEyA4",
     "status": "pending",
     "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0",
     "trustAnchors": [
       "https://trust-anchor-1.example.com",
       "https://trust-anchor-2.example.com"
     ]
   }

The openid-federation-01 challenge MUST NOT be used to validate possession of any ACME Identifiers except openid-federation ACME Identifiers.¶

The Requestor responds to the challenge with an object with the following format:¶

sig (required, string): the compact JSON serialization (as described in Section 7.1 of [RFC7515]) of a JWS, signing the key authorization encoded in UTF-8. The key authorization is computed from the token in the challenge and the Requestor's ACME account key, as defined in Section 8.1 of [RFC8555]. The signature must be made by one of the keys published in the Requestor's acme_requestor metadata in its Entity Configuration, as specified in Section 6. The JWS MUST include a kid header parameter corresponding to the key used to sign the key authorization and a typ header parameter set to "signed-acme-challenge+jwt".¶

trustChain (optional, array of string): an array of strings containing signed JWTs, representing a Trust Chain from the Requestor to one of the Issuer's Trust Anchors (see Section 4 of [OPENID-FED]). The Resolved Metadata of the Trust Chain subject MUST contain acme_requestor metadata that contains the key used to compute sig. It is RECOMMENDED that the Requestor includes this field. If the Requestor cannot construct a Trust Chain to one of the Trust Anchors indicated by the Issuer, or if no Trust Anchors were indicated, it MAY use some other Trust Anchor that it believes the Issuer trusts. If the Requestor cannot construct a Trust Chain to any Trust Anchor, it MAY omit the trustChain field from the challenge response.¶

A non-normative example for an authorization with trustChain specified:¶

   POST /acme/chall/prV_B7yEyA4
   Host: issuer.example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://issuer.example.com/acme/acct/evOfKhNU60wg",
       "nonce": "UQI1PoRi5OuXzxuX7V7wL0",
       "url": "https://issuer.example.com/acme/chall/prV_B7yEyA4"
     }),
     "payload": base64url({
      "sig": "wQAvHlPV1tVxRW0vZUa4BQ...",
      "trustChain": ["eyJhbGciOiJFU...", "eyJhbGci..."]
     }),
     "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
   }

On receiving a challenge response, the Certificate Issuer verifies that the Requestor is trusted. If the Requestor did not provide a trustChain, the Issuer MUST perform Federation Entity Discovery (Section 10 of [OPENID-FED]) to obtain a Trust Chain for the Requestor.¶

Once it has obtained a Trust Chain, the Issuer evaluates the entity's Resolved Metadata, and verifies:¶

• That the requested openid-federation ACME Identifier value matches the sub parameter of the Requestor's Entity Configuration.¶

• That there is a key in the acme_requestor metadata (Section 6) of the Requestor's Resolved Metadata with a kid matching the kid claim in the challenge response.¶

• That the sig field of the payload is the compact JSON serialization of a valid JWS signing the key authorization, using the above public key.¶

If all of the above checks succeed, then the validation is successful. Otherwise, it has failed. In either case, the Certificate Issuer responds according to Section 7.5.1 of [RFC8555]. If the Issuer fails to verify OpenID Federation trust, the problem document SHOULD contain a subproblem of type urn:ietf:params:acme:error:openIDFederationEntity constructed as discussed in Section 11.¶

A non-normative example for the challenge object post-validation:¶

   {
     "type": "openid-federation-01",
     "url": "https://issuer.example.com/acme/chall/prV_B7yEyA4",
     "status": "valid",
     "validated": "2024-10-01T12:05:13.72Z",
     "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0"
   }

6. Requestor Entity Configuration Metadata

The Requestor MUST publish in its Entity Configuration an acme_requestor metadata containing a JWK set, according to Section 5.2.1 of [OPENID-FED]. The keys in the set are used to respond to ACME challenges.¶

The following is a non-normative example of an Entity Configuration including the acme_requestor metadata and using the jwks metadata parameter.¶

{
  "iss": "https://requestor.example.com",
  "sub": "https://requestor.example.com",
  "iat": 1516239022,
  "exp": 1516298022,
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "alg": "RS256",
        "use": "sig",
        "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
        "n": "pnXBOusEANuug6ewezb9J_...",
        "e": "AQAB"
      }
    ]
  },
  "metadata": {
    "acme_requestor": {
      "jwks": {
        "keys": [
          {
            "kty": "RSA",
            "kid": "SUdtUndEWVY2cUFDeD...",
            "n": "y_Zc8rByfeRIC9fFZrD...",
            "e": "AQAB"
          },
          {
            "kty": "EC",
            "kid": "MFYycG1raTI4SkZvVDBIMF9CNGw3VEZYUmxQLVN2T21nSWlkd3",
            "crv": "P-256",
            "x": "qAOdPQROkHfZY1daGofOmSNQWpYK8c9G2m2Rbkpbd4c",
            "y": "G_7fF-T8n2vONKM15Mzj4KR_shvHBxKGjMosF6FdoPY"
          }
        ]
      }
    }
  }
}

The Issuer MUST only use the Requestor's acme_requestor to validate an ACME challenge. Therefore, after completing the challenge, the Requestor MAY remove the acme_requestor metadata from its Entity Configuration.¶

7. Issuer Discovery

The Requestor's ACME client may either be configured to use a particular ACME server, or to automatically discover a Certificate Issuer through the OpenID Federation.¶

In order to be discoverable, the Issuer MUST publish the entity type acme_issuer in its Entity Configuration, according to Section 7.1.¶

[OPENID-FED] describes a variety of patterns and generic mechanisms for discovering Federation Entities. This section describes how Issuers may make themselves discoverable in a Federation by Requestors.¶

TODO: include a specific section reference once https://github.com/openid/federation/pull/265 lands in OPENID-FED¶

{
  "iss": "https://issuer.example.com",
  "sub": "https://issuer.example.com",
  "iat": 1516239022,
  "exp": 1516298022,
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "alg": "RS256",
        "use": "sig",
        "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
        "n": "pnXBOusEANuug6ewezb9J_...",
        "e": "AQAB"
      }
    ]
  },
  "metadata": {
    "acme_issuer": {
      "directory_url": "https://issuer.example.com/acme/directory"
    }
  }
}

8. Publication of the Certificates within the Federation

The X.509 Certificates issued by federation Immediate Superior Entities pertaining to one or more Federation Entity Keys in control of their Subordinates MAY publish this information by including the x5c member in each JWK contained within the matching Subordinate Statement. The contents of the published x5c member, including whether it contains a full or partial Trust Chain, and if so, to what Trust Anchor, are policy decisions out of scope for this document.¶

9. CSR and Certificate Fields

Depending on the Certificate Issuer's X.509 Certificate profile, the CSR and X.509 Certificate MAY associate the X.509 Certificate to the Federation Entity by including the Entity Identifier in the X.509 Certificate.¶

To do so, the Issuer includes a Subject Alternative Name extension containing an otherName with a type-id of id-on-OpenIdFederationEntityId. The value of the name is an Octet String containing the UTF-8 encoding of the Entity Identifier (i.e., the URI in the corresponding openid-federation ACME Identifier from the newOrder request).¶

   id-on-OpenIdFederationEntityId OBJECT IDENTIFIER ::= { id-on XXX }

   OpenIdFederationEntityId ::= UTF8String

10. Certificate Lifecycle

The identity of the Requestor is verified through proof of possession of a private key corresponding to a public key attested within a Trust Chain. The Trust Chain has an expiration time, and its content MUST NOT be trusted past the expiration time (Section 10.2 of [OPENID-FED]).¶

The notBefore and notAfter fields of issued certificates MUST represent dates before the Trust Chain's expiration time. If the Requestor's newOrder request (Section 7.4 of [RFC8555]) contains notAfter or notBefore fields that make this impossible, the Certificate Issuer MUST reply with an error of type urn:ietf:params:acme:error:openIDFederationCertificateValidity.¶

11. Errors

This document defines two new error type URIs to be used in problem documents [RFC9457], as described in Section 6.7 of [RFC8555].¶

The error type urn:ietf:params:acme:error:openIDFederationEntity is used to encapsulate any OAuth error code returned while resolving OpenID Federation Entities. The title of this error type is "OpenID Federation Error". The detail member of the problem document MAY include the description of the particular OAuth error code that caused the error. The problem document for this error type SHOULD include an extension member named error_code, which MUST be set to the OAuth error code, taken from the error codes defined in Section 8.9 of [OPENID-FED].¶

The error type urn:ietf:params:acme:error:openIDFederationCertificateValidity is used to indicate that a Certificate could not be issued because of a mismatch between the requested period of validity and the expiration of the OpenID Federation Trust Chain.¶

12. Security Considerations

The openid-federation-01 challenge defined in Section 5 defends against replay attacks by malicious ACME servers because the signature in challenge responses is over an ACME key authorization, which binds the ACME account key.¶

The cryptographic keys in the acme_requestor metadata SHOULD NOT be reused for other purposes than signing responses to acme-federation-01 challenges. For example, the same keys SHOULD NOT be reused in the issued X.509 Certificate. If the keys are reused for other purposes, cross-protocol attacks MUST be considered.¶

The cryptographic keys in the acme_requestor metadata SHOULD be rotated periodically.¶

13. IANA Considerations

IANA is kindly asked to make the following updates to registries:¶

14. References

Appendix A. End-to-end Issuance Flow

~~~ BEGIN EDNOTE ~~~¶

This appendix is to be removed before publication.¶

This section contains explanatory material that recaps a lot of RFC 8555. It is included here for the benefit of readers who are familiar with OpenID Federation but not with ACME, and want to see at a glance how the whole thing fits together.¶

The following diagram illustrates a successful interaction between Issuer and Requestor to retrieve an X.509 Certificate. The diagram assumes the Requestor has already discovered the Issuer, and the Requestor has already created an ACME account with the Issuer.¶

This section is informational and non-normative. The remainder of this document, [RFC8555] and [OPENID-FED] should be considered correct should this appendix disagree with any of them.¶

,-----------------.
|Requestor's      |  ,-----------.
|OpenID Federation|  |Requestor's|               ,------------------------.  ,-----------------------.
| Web Server      |  |ACME Client|               |X.509 Certificate Issuer|  |Federation Trust Anchor|
`--------+--------'  `-----+-----'               `-----------+------------'  `-----------+-----------'
        |                  |           POST /acme/new-order  |                           |
        |                  |--------------------------------->                           |
        |                  |                                 |                           |
        |                  |Authorization at                 |                           |
        |                  |/acme/authz/[authz-id]           |                           |
        |                  |Finalize at                      |                           |
        |                  | /acme/order/[order-id]/finalize |                           |
        |                  |<- - - - - - - - - - - - - - - - -                           |
        |                  |                                 |                           |
        |                  | POST /acme/authz/[authz-id]     |                           |
        |                  |--------------------------------->                           |
        |                  |                                 |                           |
        |                  |  openid-federation-01 Challenge |                           |
        |                  |  at /acme/chall/[chall-id]      |                           |
        |                  |<- - - - - - - - - - - - - - - - -                           |
        |                  |                                 |                           |
        |                  ----.                             |                           |
        |                  |   | Sign challenge token        |                           |
        |                  |   | with private key            |                           |
        |                  <---'                             |                           |
        |                  |                                 |                           |
        |                  | POST /acme/chall/[chall-id]     |                           |
        |                  | with signed                     |                           |
        |                  | token and entity ID             |                           |
        |                  | set to Requestor's ID           |                           |
        |                  |--------------------------------->                           |
        |                  |                                 |                           |
        |                  |      Challenge validation       |                           |
        |                  |      beginning                  |                           |
        |                  |<- - - - - - - - - - - - - - - - -                           |
        |                  |                                 |                           |
        |          GET /.well-known/openid-federation        |                           |
        |<----------------------------------------------------                           |
        |                  |                                 |                           |
        |           Requestor's Entity Configuration         |                           |
        | - - -  - - - - - - - - - - - - - - - - - - - - - - >                           |
        |                  |                                 |                           |
        |                  |           ______________________________________________________
        |                  |           ! OPT  /  If Requestor didn't provide Trust Chain |  !
        |                  |           !_____/               |                           |  !
        |                  |           !                     |  Determine Trust Chain    |  !
        |                  |           !                     |  from Issuer's            |  !
        |                  |           !                     |  Trust Anchor to Requestor|  !
        |                  |           !                     |  (Federation Discovery)   |  !
        |                  |           !                     | <------------------------>|  !
        |                  |           !~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~!
        |                  |                                 |                           |
        |                  |                                 |----.                      |
        |                  |                                 |    | Evaluate Trust Chain |
        |                  |                                 |<---'                      |
        |                  |                                 |                           |
        |                  |                                 |----.                      |
        |                  |                                 |    | Check                |
        |                  |                                 |    | Entity Configuration |
        |                  |                                 |    | sub matches          |
        |                  |                                 |    | Entity Identifier    |
        |                  |                                 |<---' in the order         |
        |                  |                                 |                           |
        |                  |                                 |                           |
        |                  |                                 |----.                      |
        |                  |                                 |    | Check challenge      |
        |                  |                                 |    | sig is signed        |
        |                  |                                 |    | with key in          |
        |                  |                                 |<---' Entity Configuration |
        |                  |                                 |                           |
        |  _________________________________________________________________________     |
        |  ! LOOP  /  Poll until authz status                |                      !    |
        |  !      /  is "valid" or "invalid"                 |                      !    |
        |  !_____/         |                                 |                      !    |
        |  !               |    POST-as-GET                  |                      !    |
        |  !               |    /acme/authz/[authz-id]       |                      !    |
        |  !               |--------------------------------->                      !    |
        |  !               |                                 |                      !    |
        |  !               |           Current authz status  |                      !    |
        |  !               |<---------------------------------                      !    |
        |  !~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~!    |
        |                  |                                 |                           |
        |                  |                                 |                           |
        |  ___________________________________________________________________________   |
        |  ! OPT  /  If the authz status is "valid"          |                        !  |
        |  !_____/         |                                 |                        !  |
        |  !               | POST                            |                        !  |
        |  !               | /acme/orders/[order-id]/finalize|                        !  |
        |  !               | with CSR                        |                        !  |
        |  !               |--------------------------------->                        !  |
        |  !               |                                 |                        !  |
        |  !               |                                 |----.                   !  |
        |  !               |                                 |    | Check CSR         !  |
        |  !               |                                 |    | validity          !  |
        |  !               |                                 |    | according to      !  |
        |  !               |                                 |    | protocol          !  |
        |  !               |                                 |<---' and CA policy     !  |
        |  !               |                                 |                        !  |
        |  !               |                                 |                        !  |
        |  !               |  Order object with certificate  |                        !  |
        |  !               |  at /acme/cert/[cert-id]        |                        !  |
        |  !               |<- - - - - - - - - - - - - - - - -                        !  |
        |  !               |                                 |                        !  |
        |  !               |       POST /acme/cert/[cert-id] |                        !  |
        |  !               |--------------------------------->                        !  |
        |  !               |                                 |                        !  |
        |  !               |  Newly issued X.509 Certificate |                        !  |
        |  !               |<- - - - - - - - - - - - - - - - -                        !  |
        |  !~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~!  |
,--------+--------.  ,-----+-----.               ,-----------+------------.  ,-----------+-----------.
|Requestor's      |  |Requestor's|               |X.509 Certificate Issuer|  |Federation Trust Anchor|
|OpenID Federation|  |ACME Client|               `------------------------'  `-----------------------'
| Web Server      |  `-----------'
`-----------------'

~~~ END EDNOTE ~~~¶

Acknowledgments

Aaron Gable and Mike Ounsworth, for early and thorough reviews of this draft.¶

Contributors

Authors' Addresses