OPFederationWIP

Introduction

The OpenID Federation 1.0 (currently draft) specification defines components used to build multilateral federations and describes how to apply them on top of the OAuth2/OIDC stack.

The main Jira ticket to follow is https://shibboleth.atlassian.net/browse/JOIDC-222 . This is subject to change once a new Jira project is populated for the new OpenID Federation plugin to the OP plugin.

Source code access

The development is now being done on java-idp-plugin-oidc-op-oidfed repository.

The development was previously done on branch dev/JOIDC-222 in the java-idp-oidc repository, but the current approach is to provide the OpenID Federation features as a plugin/extension to the OP plugin.

See https://shibboleth.atlassian.net/wiki/spaces/DEV/pages/1137344525 for instructions on detailed instructions on how to access the source code.

Plugin (binary) snapshots

In order to deploy the current state of the work for federation feature, one needs to install (1) the latest snapshot of the OP plugin and (2) the latest snapshot of the OpenID Federation plugin for OP. The links to the latest snapshots can be found from the following endpoints:

• OP: https://build.shibboleth.net/maven/snapshots/net/shibboleth/idp/plugin/oidc/idp-plugin-oidc-op-distribution/4.4.0-SNAPSHOT/

• Federation plugin: https://build.shibboleth.net/nexus-proxy/content/repositories/snapshots/net/shibboleth/idp/plugin/oidfed/idp-plugin-oidfed-op-dist/1.0.0-SNAPSHOT/

The tar.gz packages with the latest timestamps should be used.

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

Make sure that the latest release versions of these plugins are installed (see https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376878882 ):

• net.shibboleth.oidc.common (3.0.0 or later)

• net.shibboleth.idp.plugin.oidc.config (3.0.0 or later)

Configuration

First configure the standard OIDC/OAuth2 feature as described here: https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376878976/OIDC+OP#Initial-Setup . Also note that ES384 and ES512 credentials are not included in the basic example, but the section https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376878976/OIDC+OP#Key-Generation-for-ES384-and-ES512 describes how to generate and enable them.

Regarding the publication of OP’s own configuration, follow the instructions for dynamic publication: https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376879256/OPDiscovery#Configuration . As documented on the page, this part contains editing of static/openid-configuration.json file and configuring servlet container to redirect /.well-known/openid-configuration requests into the oidc/configuration flow.

Federation configuration

Trust anchors

The locally trusted trust anchors need to be configured in conf/oidfed/oidfed-trust-anchors.json (NOTE! In earlier versions the file was located in conf-directory, not in its oidfed-subfolder). 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,

Entity configuration

1. 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-es521.jwk

2. Refer to the new key in conf/oidc-credentials.xml

   1. ... <bean id="shibboleth.oidfed.DefaultES521SigningCredential" parent="shibboleth.JWKCredential" p:resource="/opt/shibboleth-idp/credentials/fed-signing-es521.jwk" /> <util:list id="shibboleth.oidfed.SigningCredentials"> <ref bean="shibboleth.oidfed.DefaultES521SigningCredential" /> </util:list> ...

3. Define a signing algorithm that is compatible with the key (conf/oidc.properties)

   1. idp.oidfed.entity.sigalg = ES512

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

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

5. Register your OP with a federation authority

   1. This is obviously out of scope of the plugin itself, but in the end the authority should be included in the authority_hints in your entity configuration. In the example above, the OP is registered to https://ia1.oidf-pilot.edugain.org intermediate authority.

   2. idp.oidfed.entity.authorityHints = https://ia1.oidf-pilot.edugain.org

Finally, the servlet container needs to be configured to redirect /.well-known/openid-federation requests into the oidfed/entity-configuration flow.

After changes have been applied, the endpoint should be responding with the entity configuration.

Automatic registration

1. Enable OIDFED.AutomaticRegistration for shibboleth.DefaultRelyingParty in conf/relying-party.xml

   1. ... <bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty"> <property name="profileConfigurations"> <list> <ref bean="OIDC.SSO" /> <ref bean="OIDC.UserInfo"/> <ref bean="OAUTH2.Token"/> <ref bean="OAUTH2.Revocation"/> <ref bean="OAUTH2.Introspection" /> <ref bean="OAUTH2.PAR" /> <bean parent="OIDFED.AutomaticRegistration" /> </list> </property> </bean> ...

2. Enable automatically registered RPs access per flow/endpoint (conf/oidc.properties):

   1. idp.oidfed.authorize.automaticRegistrationCondition = shibboleth.Conditions.TRUE idp.oidfed.token.automaticRegistrationCondition = shibboleth.Conditions.TRUE idp.oidfed.userinfo.automaticRegistrationCondition = shibboleth.Conditions.TRUE

Trust Chain Resolution method

By default, all the valid trust chains for the incoming RP are resolved locally. The valid trust anchors are configured as described in sectionhttps://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/4500914216/OPFederationWIP#Trust-anchors.

The property idp.oidfed.trustchain.resolver.useResolverApiCondition may be used for defining a condition when a remote resolve entity API would be used instead of the local resolution. By default, its value is shibboleth.Conditions.FALSE. A value shibboleth.Conditions.TRUE would mean that remote resolution is always attempted.

Another property idp.oidfed.trustchain.resolver.fallbackToLocalCondition may be used for controlling whether or not to fall back into local resolution if the remote resolution fails. By default its value is shibboleth.Conditions.TRUE.

Remote Trust Chain resolution endpoints

If the condition for using remote resolver entity API returns true for the incoming client, by default the configuration in the conf/oidfed/oidfed-trustchain-resolver.xml -file is exploited.

The example above configures an entity https://trust-anchor.federation.local to be trusted for remote resolution. Its federation_resolve_endpointis automatically fetched and used as the endpoint together with the two trust_anchors parameters as specified by the c:anchors value. It could also contain a single value. Multiple values are separated by commas. Only the trust anchors that are locally trusted (see https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/4500914216/OPFederationWIP#Trust-anchors ) are used: others are filtered out.

Resolve Entity API

Enable OIDFED.ResolveEntity for shibboleth.DefaultRelyingParty in conf/relying-party.xml

Remarks:

• Currently the Resolve Entity API doesn’t support client authentication

• The Resolve Entity API exploits the same trust anchor configuration as automatic registration (via conf/oidfed/oidfed-trust-anchors.json).