OpenID Federation 1.0 provides a framework to build trust between a Relying Party and an OpenID Provider that have no direct relationship so that the Relying Party can send OIDC/OAuth requests to the OpenID Provider without being previously authorized from that directly.
One primary use case is the trust between an Issuer and a Holder on W3C’s Verifiable Credential(VC) Data Model, which is getting a lot of attention as an approach to realize the Digital Identity Wallet ecosystem. (In that context, the word “Wallet” is used instead of “Holder”.)
OpenID Foundation provides a couple of specifications based on widely used OIDC/OAuth, such as OpenID for Verifiable Credentials Issuance (OID4VCI), where an OpenID Provider as Issuer provides Verifiable Credentials, VCs (protected resources in OAuth term) to a Relying Party as Holder (Wallet).
But in the Digital Identity Wallet ecosystem, the Holder (Wallet) is usually provided as Mobile Native Application and that is classified as a “public” client in OIDC/OAuth terms. It is because they are distributed from application download services of each mobile platform and can not easily issue their client secrets in a safe manner.
Here using Dynamic Client Registration to provision per-instance secrets is recommended to mitigate that risk.
And OpenID Federation can provide a more secure way to realize the provisioning, which makes it easier to implement issuing VCs to the Wallet especially in use cases of accessing sensitive data.
Keycloak, Identity and Access Management OSS, is working towards implementing OpenID Federation, and it is attracting attention as a component that plays a central role in the Digital Identity Wallet ecosystem.
This article provides how to use OpenID Federation Trust Chain for building trust with 3-rd parties using Keycloak step-by-step.
Overview of OpenID Federation trust framework
In OIDC/OAuth, a Relying Party and an OpenID Provider have a direct relationship, which means that a Relying Party has registered with an OpenID Provider in advance. When the OpenID Provider gets the registration request from the Relying Party, it has to know that the Relying Party is reliable enough. For that purpose, OpenID Providers usually provide a GUI tool like an admin console for an administrator to register applications or get credentials to use for calling a client registration endpoint.
OpenID Federation is a framework to build trust between a Relying Party and an OpenID Provider before registration or without pre-registration.
It can be described with the figure below:
OpenID Provider A has a direct relationship with Relying Party A-1/ A-2. On the other hand, Relying Party B does not have a direct relationship with OpenID Provider A. Based on OpenID Federation Trust Chain, OpenID Provider A trusts Relying Party B so that OpenID Provider A accepts OIDC/OAuth requests from Relying Party B without prior registration or sharing credentials for registration.
Relying Party B is authorized by the Trust Chain, which is built by third-party authorities. One is a Trust Anchor, which is the origin of a trust chain. The other is an Intermediate Authority, which is authorized by the Trust Anchor.
In this article, we use Keycloak as the OpenID Provider and show you how to register a client dynamically with OpenID Federation Trust Chain.
For registering a client, there are two approaches defined in OpenID Federation and we adapt Explicit Client Registration, which is suitable for implementation on top of the OpenID Connect Dynamic Client Registration 1.0 endpoint of an OpenID Provider deployment. It enables an OpenID Provider to provision a Client ID, potentially a Client Secret, and other metadata parameters.
The flow detail of Explicit Client Registration is something like the following figure:
Here the OpenID provider receives Dynamic Client Registration request with the Entity Configuration of the Relying Party. This includes information about the Relying Party itself such as endpoints of authorities, which authorize the Relying Party.
The OpenID provider then sends the request to the one of the authorities, usually called Intermediate Authority, for getting the Entity Configuration of that and the Subordinate Statement which is the statement about a subordinate entity, the Relying Party in this case, with the digital signature of the Intermediate Authority.
If the Entity Configuration includes endpoints of authorities again, which authorize the Intermediate Authority, the OpenID provider then sends the request to the one of the authorities for getting the Entity Configuration and the Subordinate Statement pretty much same way as before until the OpenID provider gets the Entity Configuration of the Trust Anchor, of which the Entity Configuration does not include any endpoints of authorities.
In the below tutorial, we show how to prepare a PoC environment for building trust with OpenID Federation Trust Chain. We use Keycloak as OpenID Provider, which provides a customized dynamic client registration endpoint with OpenID Federation plugin. And it accepts a request with OpenID Federation Trust Chain, validates that with Intermediate Authority/Trust Anchor, and creates a client.
About a PoC environment
The table below shows the system configuration for each component of a PoC environment.
And the list below is the steps for preparing those components and performing Explicit Client Registration;
- Set up a mock server for Trust Anchor
- Set up a mock server for Intermediate Authority
- Set up Keycloak as OpenID Provider
- Perform Explicit Client Registration with OpenID Federation Trust Chain
From the next section, the details of each steps is explained one by one.
Set up a mock server for Trust Anchor
First, prepare a trust anchor as a mock server with two endpoints.
1.Federation Entity Configuration endpoint
A HTTP GET request with the path /.well-known/openid-configuration looks like this:
And the GET returns JWT, which payload is like below:
This statement is information about the Trust Anchor, so both “iss” and “sub” are the Trust Anchor itself. The “metadata” is the one about this Trust Anchor and among those the most important claim here is “federation_api_endpoint”, which issues Subordinate Statement like the next section.
2. Subordinate Statement Endpoint
The HTTP GET request with the path /oidc/fedapi(*) looks like below:
(*)”federation_api_endpoint “ in Entity Configuration tells you which path you should use here.
Query parameter “iss” is the one to specify who issues the requested Subordinate Statement. That is the Trust Anchor here, who also signs that statement. And Query parameter “sub” is the one to specify who is the subject of that statement. That is the Intermediate Authority here, who is authorized by the Issuer with that sign.
And the GET returns JWT, which payload is like below:
This statement is information about the Intermediate Authority in “sub” and signed by the Trust Anchor in “iss”. A public key in this statement is the Intermediate Authority’s and signed by a private key of the Trust Anchor, like X.509 certificate.
The Intermediate Authority mentioned here is set up in the following step.
Set up a mock server for Intermediate Authority
Then prepare an Intermediate Authority as a mock server with two endpoints.
1.Federation Entity Configuration endpoint
A HTTP GET request with the path /.well-known/openid-configuration looks like this:
And the GET returns JWT, which payload is like below:
Here “authority_hints” is a list of authorities who can authorize this Intermediate Authority and which should include the Trust Anchor described in the previous step. This statement is information about the Intermediate Authority itself as same as the one for the Trust Anchor.
2. Subordinate Statement Endpoint
A HTTP GET request with the path /oidc/fedapi(*) looks like below:
(*)”federation_api_endpoint “ in Entity Configuration tells you which path you should use here.
Query parameter “iss” is the one to specify who issues the requested Subordinate Statement. That is the Intermediate Authority here, who also signs that statement. And Query parameter “sub” is the one to specify who is the subject of that statement. That is the Relying Party here, who is authorized by the Issuer with that sign.
And the GET returns JWT, which payload is like below:
This statement is information about the Relying Party in “sub” and signed by the Intermediate Authority in “iss”. A public key in this statement is the Relying Party’s and signed by a private key of the Intermediate Authority, like X.509 certificate.
Set up Keycloak as OpenID provider
Finally prepare Keycloak as OpenID Provider:
First, install Keycloak. Download and unzip the Keycloak.
Next, install the Keycloak OpenID Federation plugin. Copy the jar file created in the target directory using the commands below to the Keycloak providers directory.
Then, start Keycloak.
Access the 8080 port of the Keycloak host and log in to the admin console with the administrator username/password.
Create a realm “fed01”.
Register a trust anchor for the new realm:
Perform explicit client registration with OpenID Federation trust chain
Now your Keycloak is all ready for Explicit Client Registration.
Then, for the Explicit Client Registration request, prepare JWT, which payload is like below:
This statement is information about the Relying Party, so both “iss” and “sub” are the Relying Party itself. On the other hand, “aud” is the OpenID provider which receives this registration request. The “metadata” is the one about this Relying Party, which includes OIDC/OAuth related ones, such as “jwks_uri”, “redirect_uris”. And most importantly “authority_hints” is a list of authorities who can authorize this Relying Party, usually the list of Intermediate Authorities.
And send a HTTP POST request with the JWT above:
Finally, check if a new client is created on admin console like below:
As a result, you can see here the client you have just created by Explicit Client Registration.
Conclusion
In this article, I explained how to build trust between a 3-rd party Relying Party and Keycloak as an OpenID Provider with OpenID Federation Trust Chain.
Currently in the Keycloak community, OAuth-SIG (a group whose activity is mainly supporting OIDC/OAuth and its related security features to Keycloak) discusses how to enhance Keycloak to build the Digital Identity Wallet ecosystem, for which we believe OpenID Federation plays a crucial role and we are taking an initiative to include the OpenID Federation functionality into Keycloak.