​

Introduction

​

Overview

​

Trust Chain

​

JWT Issued by Leaf Entity

​

JWT Issued by Intermediate Authority

​

JWT Issued by Trust Anchor

​

Trust Chain Summary

​

Trust Chain Resolution

​

Entity Configuration

Leaf Entity's Identifier + /.well-known/openid-federation

https://rp.example.com/123/.well-known/openid-federation

​

Authority Hints

​

Federation Fetch Endpoint

https://ia.example.com/fetch?sub=https://rp.example.com/123

​

Trust Chain Resolution Flow

​

Trust Chain Resolution Summary

​

Metadata

​

Identity Provider Metadata

• client_registration_types_supported
• organization_name
• federation_registration_endpoint
• request_authentication_methods_supported
• request_authentication_signing_alg_values_supported
• signed_jwks_uri
• jwks

​

Relying Party Metadata

• client_registration_types
• organization_name
• signed_jwks_uri

​

Authority Metadata

• federation_fetch_endpoint
• federation_list_endpoint
• federation_resolve_endpoint
• federation_trust_mark_status_endpoint
• organization_name
• contacts
• logo_uri
• policy_uri
• homepage_uri

​

Metadata Policy

​

Client Registration

https://idp.example.com/authorize?request_uri=...&client_id=https://rp.example.com/123

​

Automatic Client Registration

​

Request Authentication

1. request_object - Request object signed with an asymmetric algorithm.
2. private_key_jwt - Client authentication using client assertion.
3. tls_client_auth - Client authentication using X.509 certificate.
4. self_signed_tls_client_auth - Client authentication using X.509 certificate.

​

Explicit Client Registration

1. Entity configuration. Its Content-Type is application/entity-statement+jwt.
2. Trust chain, a JSON array listing entity statements. Its Content-Type is application/trust-chain+json.

​

Automatic Client Update

​

The trust_chain Request Parameter

​

Authlete Implementation

​

Version

​

Feature Availability

1. Authlete Server must be deployed with feature.oidc_federation.enabled=true.
2. The federationEnabled flag of Service must be true. (cf. Service.setFederationEnabled(boolean))

1. At least one authority (intermediate authority or trust anchor) must be registered. Otherwise, the service cannot generate its entity configuration. (cf. Service.setAuthorityHints(URI[]))
2. At least one pair of trust anchor and its JWK Set must be registered. Otherwise, the service cannot trust any trust chain. (cf. Service.setTrustAnchors(TrustAnchor[]))
3. At least one private key dedicated to OpenID Federation must be registered. Otherwise, the service cannot sign entity statements. (cf. Service.setFederationJwks(String))
4. At least either of automatic client registration or explicit client registration must be supported. Otherwise, the service cannot register federation clients. (cf. Service.setSupportedClientRegistrationTypes(ClientRegistrationType[]))

​

Configuring Federation

1. Log in to the Authlete Management Console.
2. Navigate to Service Settings > Endpoints > Federation.
3. In the Federation Support section, enable the toggle to activate OpenID Connect Federation 1.0 support.
4. Under Client Registration Types, select one or both registration methods:
   • Automatic: Enables automatic client registration.
   • Explicit: Enables explicit client registration.
5. In the Registration Endpoint field, provide the URI for the federation registration endpoint (e.g., https://idp.example.com/fedreg).
6. Click Save Changes to apply the configuration.

​

Authlete API

​

The /api/federation/configuration API

@Path("/.well-known/openid-federation")
public class FederationConfigurationEndpoint extends BaseFederationConfigurationEndpoint
{
    /**
     * Entity configuration endpoint.
     */
    @GET
    public Response get()
    {
        // Handle the request to the endpoint.
        return handle(AuthleteApiFactory.getDefaultApi());
    }
}

​

The /api/federation/registration API

@Path("/api/federation/register")
public class FederationRegistrationEndpoint extends BaseFederationRegistrationEndpoint
{
    @POST
    @Consumes("application/entity-statement+jwt")
    public Response entityConfiguration(String jwt)
    {
        // Client registration by a relying party's entity configuration.
        return handle(
                AuthleteApiFactory.getDefaultApi(),
                request().setEntityConfiguration(jwt));
    }


    @POST
    @Consumes("application/trust-chain+json")
    public Response trustChain(String json)
    {
        // Client registration by a relying party's trust chain.
        return handle(
                AuthleteApiFactory.getDefaultApi(),
                request().setTrustChain(json));
    }


    private static FederationRegistrationRequest request()
    {
        return new FederationRegistrationRequest();
    }
}

​

Client Registration and Update

​

Automatic Client Registration

1. When Authlete processes an OAuth/OIDC request, Authlete tries to identify a client at a relatively early phase. First, Authlete interprets the specified client identifier as an original numeric ID and searches the database for a client having the numeric ID.
2. If a client having the numeric ID was not found, but if the “Client ID Alias” feature of the service is enabled, Authlete interprets the specified client identifier as an alias and searches the database for a client having the alias.
3. If a client having the alias was not found, but if the “OpenID Federation” feature of the service is enabled, Authlete interprets the specified client identifier as an entity ID and searches the database for a client having the entity ID.
4. If a client having the entity ID was not found, but if the service supports automatic client registration, Authlete tries to resolve a trust chain of the client.
5. If the trust chain resolution succeeds, Authlete applies the combined metadata policy of the trust chain to the metadata of the client.
6. Authlete checks whether the client metadata contains the client_registration_types client metadata and it includes automatic.
7. Authlete validates the client metadata to ensure that the client can be registered to the service.
8. Authlete performs request authentication for the OAuth/OIDC request.
9. Finally, Authlete registers the client and continues to process the OAuth/OIDC request.

​

Trust Chain Update

1. If the “OpenID Federation” feature of the service is not enabled, Authlete does not try to update trust chains.
2. Authlete checks whether the service supports automatic client registration and whether the client’s client_registration_types metadata contains automatic. If these conditions are not satisfied, an error is returned.
3. Authlete validates the trust chain specified by the trust_chain request parameter. Especially, the entity ID of the entity configuration in the trust chain must match the entity ID of the existing client.
4. Authlete applies the combined metadata policy of the trust chain to the client metadata in the trust chain.
5. Authlete checks whether the client metadata contains the client_registration_types client metadata and it includes automatic.
6. Authlete validates the client metadata to ensure that the client can be updated with the metadata.
7. Authlete updates metadata of the client.
8. Authlete continues to process the OAuth/OIDC request.

1. If the “OpenID Federation” feature of the service is not enabled, Authlete does not try to update trust chains.
2. Authlete checks whether the current trust chain of the client has expired. If the trust chain has not expired, Authlete does not try to update the trust chain.
3. If the current trust chain has expired but the service does not support automatic client registration, the client is deleted and the OAuth/OIDC request fails.
4. If the current trust chain has expired but automatic is not included in the client_registration_types client metadata, the client is deleted and the OAuth/OIDC request fails.
5. Authlete builds a trust chain from the entity ID of the client from scratch.
6. Authlete applies the combined metadata policy of the trust chain to the client metadata in the trust chain.
7. Authlete checks whether the client metadata contains the client_registration_types client metadata and it includes automatic.
8. Authlete validates the client metadata to ensure that the client can be updated with the metadata.
9. Authlete updates metadata of the client.
10. Authlete continues to process the OAuth/OIDC request.

​

Finally