OPDiscovery

File(s): conf/relying-party.xml, conf/oidc.properties, static/openid-configuration.json
Format: Native Spring, Spring Properties, JSON

1 Overview
2 Configuration
- 2.1 Static Publication
- 2.2 Dynamic Publication
  - 2.2.1 Jetty 9.4 Example
    - 2.2.1.1 etc/rewrite-rules.xml
  - 2.2.2 Tomcat Example
    - 2.2.2.1 catalina-base/conf/server.xml :
    - 2.2.2.2 catalina-base/conf/Catalina/localhost/rewrite.config :
  - 2.2.3 Activation
  - 2.2.4 Customization
3 Reference

Overview

There are two features that provide for OP discovery by clients via the OpenID Connect Discovery 1.0 specification, WebFinger and OP metadata discovery. The former isn't really applicable to this implementation because we don't provide any indirection between the WebFinger endpoint and the OP host since they're the same.

Because OIDC Discovery relies on a well-known URL at the root of the server (which the IdP does not control), this is not something the IdP can implement by itself. The web server has to cooperate by mapping the appropriate path to the functionality within the IdP, so the specifics depend on that web server. The documentation addresses Jetty 9.4 since that is the only recommended servlet container, but Jetty does evolve and the examples may become invalid over time.

Configuration

The plugin installs a template file to static/openid-configuration.json. This file requires some degree of manual adjustment, but subsequently can be used in one of two ways, served statically or as the basis of a flow implemented within the plugin that can adjust some (but not all) of the information based on the configuration. The latter is generally recommended, though the former may offload some processing load from the IdP.

Again, some of the file's content must be manually updated to correspond to configuration choices in other files (e.g., documenting claims and supported grant types). The standard content of the metadata file is specified in the OpenID Connect Discovery 1.0 specification.

Static Publication

To publish the file statically, the web server must be configured to map requests for /.well-known/openid-configuration to the static/openid-configuration.json file. This is server-dependent, and the server must also set the resulting Content-Type to "application/json".

Dynamic Publication

To publish the file dynamically, the web server must be configured to map requests for /.well-known/openid-configuration to /idp/profile/oidc/configuration. This is server-dependent but typically can be done with rewrite mechanisms.

Jetty 9.4 Example

Jetty includes a rewrite module, which can be activated by running (from the JETTY_BASE location):

$ java -jar $JETTY_HOME/start.jar --add-to-start=rewrite

This stages the rewrite.ini file to enable the module. To add rules, you must add your own file such as etc/rewrite-rules.xml, and ensure that file is loaded by Jetty by editing one of your ini files to include it. An example rule file:

etc/rewrite-rules.xml

<?xml version="1.0"?><!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<!-- =============================================================== -->
<!-- Configure the demos                                             -->
<!-- =============================================================== -->
<Configure id="Server" class="org.eclipse.jetty.server.Server">

  <!-- ============================================================= -->
  <!-- Add rewrite rules                                             -->
  <!-- ============================================================= -->
  <Ref refid="Rewrite">

      <Call name="addRule">
        <Arg>
          <New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule">
            <Set name="pattern">/.well-known/openid-configuration</Set>
            <Set name="replacement">/idp/profile/oidc/configuration</Set>
          </New>
        </Arg>
      </Call>

  </Ref>
</Configure>

Tomcat Example

Tomcat includes a rewrite valve.

catalina-base/conf/server.xml :

<Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true">
            
    <Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />

catalina-base/conf/Catalina/localhost/rewrite.config :

Note : the rewrite rule should probably end with the [L] flag.

Activation

Support for dynamic discovery is enabled by enabling a profile configuration bean called (or inherited from) "OIDC.Configuration". The clients (RPs) cannot be authenticated during the discovery sequence, so the only way to enable this profile is via the shibboleth.UnverifiedRelyingParty bean (see RelyingPartyConfiguration) since the RP by definition isn't verified.

The profile has no meaningful options that are likely to be adjusted here.

Customization

The idp.oidc.discovery.template property may be used to override the location of the static template that forms the basis of the response.

Reference

Properties related to discovery in conf/oidc.properties are:

Name	Type	Default	Description

Name	Type	Default	Description
idp.oidc.discovery.template	File pathname	%{idp.home}/static/openid-configuration.json	Location of discovery template to use
idp.oidc.discovery.resolver	Bean ID	shibboleth.oidc.DefaultOpenIdConfigurationResolver	Implementation bean for discovery, shouldn't require alteration

Beans related to discovery:

Name	Type	Description

Name	Type	Description
shibboleth.oidc.OpenIDConfiguration ^3.1	Resource	Optional hook for defining a wholly different Spring resource type for the discovery template