OIDFEDCommon

1 Overview
2 Plugin Installation
- 2.1 Installation example
3 Configuration overview
- 3.1 Entity configuration
  - 3.1.1 Federation entity key
  - 3.1.2 Authority hints
  - 3.1.3 Profile configuration
- 3.2 Trust anchors

Overview

This plugin provides reusable OpenID Federation (OIDFED) Java components which are common across Shibboleth OIDFED-dependent plugin functionality. It prevents duplication of libraries and conflicts when combining features. Its module ID will generally increment when incompatible changes occur. It also provides some deployer features such as entity configuration publication and a trust chain resolution tool.

This plugin is under construction and all the features are still subject to change.

Plugin Installation

Plugin	Plugin ID	Module ID	Depends on

Plugin	Plugin ID	Module ID	Depends on
OIDFED Common components	net.shibboleth.oidfed.common	idp.oidfed.common	idp.oidc.common.7 (SNAPSHOT)

The current (work in progress) version of the plugin requires the latest snapshot of OpenID Connect Common Library to be installed. The most convenient way to find the links to the latest snapshots is via Shibboleth IdP and Plugins status page. It contains a Current Snapshot column that contains link to the corresponding plugin.

The snapshot distribution package is signed with the Shibboleth Jenkins' key. To use that key as the truststore, download it from https://shibboleth.net/downloads/SHIBBOLETH_SNAPSHOT_PGP_KEYS.

Installation example

cd /opt/shibboleth-idp
wget https://shibboleth.net/downloads/SHIBBOLETH_SNAPSHOT_PGP_KEYS
sh bin/plugin.sh --noCheck --truststore SHIBBOLETH_SNAPSHOT_PGP_KEYS -i https://build.shibboleth.net/maven/snapshots/net/shibboleth/oidc/oidc-common-dist/3.4.0-SNAPSHOT/oidc-common-dist-3.4.0-20260902.012051-250.tar.gz
sh bin/plugin.sh --noCheck --truststore SHIBBOLETH_SNAPSHOT_PGP_KEYS -i https://build.shibboleth.net/maven/snapshots/net/shibboleth/oidfed/oidfed-common-dist/1.0.0-SNAPSHOT/oidfed-common-dist-1.0.0-20260901.134726-5.tar.gz

Configuration overview

The distribution package deploys the following files into conf/oidfed directory:

oidfed.properties - configuration properties related to OpenID Federation
oidfed-entity-configuration-claims.xml - configuration for entity configuration claims (e.g. trust marks)
oidfed-entity-configuration-metadata.json - skeleton file for entity configuration’s metadata claim
oidfed-trust-anchors.json - configuration for trust anchor keys
oidfed-trustchain-resolver.xml - configuration for (remote) resolve entity API

The following subsections describe the minimum required configuration for the features to operate. All available configuration settings are included in their respective subpages.

Entity configuration

See below the minimum required steps in order to publish an entity configuration. Finally, the web server needs to be configured to redirect /.well-known/openid-federation requests into the oidfed/entity-configuration flow (see OIDFEDEntityConfiguration | Web server configuration ).

First, define the entity ID via idp.oidfed.entityIDproperty in conf/oidfed/oidfed.properties:

idp.oidfed.entityID = https://entity.example.org

Federation entity key

Define the signing algorithm for the entity configuration: property idp.oidfed.entityConfiguration.sigalg in conf/oidfed/oidfed.properties
1. idp.oidfed.entityConfiguration.sigalg = ES512
Generate a new key pair for the federation entity (ES512 in this example)
1. cd /opt/shibboleth-idp bin/jwtgen.sh -t EC -c P-521 -u sig -i defaultECFedSign | tail -n +2 > credentials/fed-signing-es512.jwk
Refer to the new key in conf/credentials.xml
1. ... <bean id="shibboleth.oidfed.DefaultES512SigningCredential" parent="shibboleth.JWKCredential" p:resource="/opt/shibboleth-idp/credentials/fed-signing-es512.jwk" /> <util:list id="shibboleth.oidfed.SigningCredentials"> <ref bean="shibboleth.oidfed.DefaultES512SigningCredential" /> </util:list> ...

Authority hints

Register your entity with a federation authority and include it in authority hints: property idp.oidfed.entityConfiguration.authorityHints in conf/oidfed/oidfed.properties

idp.oidfed.entityConfiguration.authorityHints = https://your.authority.example.org

Profile configuration

Enable OIDFED.Configuration for shibboleth.UnverifiedRelyingParty in conf/relying-party.xml

...
    <bean id="shibboleth.UnverifiedRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
                ...
                <bean parent="OIDFED.Configuration" />
            </list>
        </property>
    </bean>
...

Trust anchors

The locally trusted trust anchors need to be configured in conf/oidfed/oidfed-trust-anchors.json

The file is a JSON file, containing a map of trust anchor identifiers to their locally trusted JWK sets. The contents below is just an example and not up-to-date keyset for the example trust anchor: fetch the current keyset by other means.

{
    "https://ta.oidf-pilot.edugain.org": {
        "keys": [
            {
                "alg": "ES512",
                "crv": "P-521",
                "kid": "vwOKov9Lo5z4cPqVpgcTsFtbaryfv8Lb_UhT2sMACuc",
                "kty": "EC",
                "use": "sig",
                "x": "ARl3Tch9N0dYO7El-UBFss3_dsGvm1ehj4i_z7c26TXYJ9LxFYcqVDa1Dla5QUBpAp1bs2NOLFz_txwmFz4z9wJB",
                "y": "Ac5wwr2RPrDE7R0mk691iC1k31KQRxlgacKsNAnEJ2auYdMn3p1kIKfxSHsALBmVyt-NTjzihvtL9JvnPjOLOgDY"
            }
        ]
    }
}