The Shibboleth IdP V4 software will leave support on September 1, 2024.

HelloWorldConfiguration

This feature requires V4.1 of the software.

Current File(s): conf/admin/admin.properties, conf/admin/hello-world.js, views/admin/hello.vm
Format: Native Spring, Velocity, Properties

Overview

The "hello" or "hello world" flow is a feature provided to ease the initial deployment and testing of the core "back-end" behavior of the IdP, such as authentication and attribute resolution. Because it does not require an SP to function, it's possible to log in, resolve attributes, and dump the result to the user locally, which avoids the awkward "just testing" stage that has traditionally complicated the early use of the software.

Depending on installation choices, it's also possible to enable it out of the box along with a dummy username, password, and attribute configuration for initial evaluation.

Enabling Module (V4.1+)

For V4.1+, configuring and using this feature requires that you first enable the "idp.admin.Hello" module if it isn't already enabled.

(Windows) C:\opt\shibboleth-idp> bin\module.bat -t idp.admin.Hello || bin\module.bat -e idp.admin.Hello (Other) $ bin/module.sh -t idp.admin.Hello || bin/module.sh -e idp.admin.Hello

By default this feature is available at /idp/profile/admin/hello

Configuration

The flow is functional by default but some of its behavior can be adjusted via admin/admin.properties. Note however that this file is ignored by upgraded systems unless  steps noted in the AdministrativeConfiguration topic are taken to allow it to be found and loaded. Absent this, the flow will operate with default values of each property.

If you prefer to customize this flow via XML or wish to apply settings not supported by properties, you can override the flow descriptor by creating your own bean (see the Flow Descriptor example in the Reference below.

The defaults assume that the rule for accessing the flow is that the user must login first, attributes will be resolved, and that a map entry will be defined in conf/access-control.xml keyed under "AccessByAdminUser" that defines who can access the flow. The access control features are described under AccessControlConfiguration, and are obviously fully generic (even wide open if desired).

There's total flexibility on this, it's up to you to define the behavior. You can even set properties that typically are used in relying-party.xml like defaultAuthenticationMethods to control what kind of authentication has to be done (e.g. requiring MFA) and many other general features of the software related to authentication.

Simulating Errors

This flow is so basic that it doesn't really have any required configuration in its own right, instead allowing testing of much of the rest of the configuration needed for a functioning IdP.

One optional feature is support for a server-side scriptlet file in conf/admin/hello-world.js. If supplied, this is a script taking as input the ProfileRequestContext just prior to the completion of the flow. If the script returns a null value, the flow completes. If the script returns any other string value, the string will become an error "event" that completes the flow abnormally.

This allows the IdP's ErrorHandlingConfiguration to be simulated by observing the result of processing a terminating error event.

It is also possible for the script to perform any other desired manipulation of the internal state of the IdP, which facilitates experimentation and exploration of the internals.

User Interface

The user interface for this flow is supplied by the template in views/admin/hello.vm and the default view illustrates a simple dump of information from the authentication and attribute resolution process.

Reference

The general properties configuring this flow via admin/admin.properties are:

Name

Default

Description

Name

Default

Description

idp.Hello.logging

Hello

Audit log identifier for flow

idp.Hello.accessPolicy

AccessByAdminUser

Name of access control policy for request authorization

idp.Hello.authenticated

true

Whether authentication should be performed prior to access control evaluation

idp.Hello.nonBrowserSupported

false

Whether the flow should allow for non-browser clients during authentication

idp.Hello.resolveAttributes

true

Whether attributes should be resolved prior to access control evaluation

To replace the internally defined flow descriptor bean, the following XML is required:

<util:list id="shibboleth.AvailableAdminFlows"> <bean parent="shibboleth.AdminFlow" c:id="http://shibboleth.net/ns/profiles/hello" p:loggingId="%{idp.hello.logging:Hello}" p:policyName="%{idp.hello.accessPolicy:AccessByAdminUser}" p:nonBrowserSupported="%{idp.hello.nonBrowserSupported:false}" p:authenticated="%{idp.hello.authenticated:true}" p:resolveAttributes="%{idp.hello.resolveAttributes:true}" /> </util:list>

In older versions and upgraded systems, this list is defined in conf/admin/general-admin.xml. In V4.1+, no default version of the list is provided and it may simply be placed in conf/global.xml if needed.