Versions Compared

Old Version 16

changes.mady.by.user Scott Cantor

Saved on

compared with

New Version 17

changes.mady.by.user Rod Widdowson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

If the flow believes that it's done this successfully, it records that fact so that if it runs again it simply skips these steps. If it detects a failure, it leaves any remaining work undone and redisplays the form, and the log should usually indicate what didn't work. This is not meant as a fancy GUI for remote use without access to the server and the logs.

localtab-livetrue
Localtabgroup
Expand
titleV4.0

To get this working, the flow has to be defined and enabled in conf/admin/general-admin.xml, and some Spring beans defined to describe to the flow what it needs to unlock.

Enable the Flow

The following is added to (or uncommented in) the shibboleth.AvailableAdminFlows list bean:

Added to conf/admin/general-admin.xml
Code Block
languagexml
<bean parent="shibboleth.OneTimeAdminFlow"
	c:id="http://shibboleth.net/ns/profiles/unlock-keys"
    p:loggingId="UnlockKeys"
	p:authenticated="true"
	p:policyName="AccessByAdminUser" />

The last couple of settings are deployment-specific. This example presumes that the rule for accessing the flow is that the user must login first, and that a map entry will be defined in conf/access-control.xml keyed under "AccessByAdminUser" that defines which usernames can access the flow. The access control features are described under AccessControlConfiguration.

There's total flexibility on this, it's up to you to define the rules. You can even set bean 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). Authentication in general won't rely on the keys being unlocked here, so there won't usually be any circular dependency there.

Localtab live
active
Expand
titleV4.1+

To get this working, the module must be enabled (as mentioned above) and some Spring beans defined to describe to the flow what it needs to unlock.

Controlling Access to the Flow

There are properties in conf/admin/admin.properties that will control the use of authentication and the access control rule applied to the flow. These are deployment-specific, but the defaults assume that the rule for accessing the flow is that the user must login first but grants no access.

The idp.unlock.accessPolicy property can be set to "AccessByAdminUser" and a map entry defined in conf/access-control.xml keyed under "AccessByAdminUser" that defines which usernames can access the flow. These access control features are described under AccessControlConfiguration.

You can even set bean 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). Authentication in general won't rely on the keys being unlocked here, so there won't usually be any circular dependency there.

If you want 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. With this in place, you can add other properties to the bean (such as defaultAuthenticationMethods) to adjust behavior.

...

The template also illustrates a useful idea of embedding a SSO push link that can be used at the end to verify that the unlocked IdP works correctly (though you'd have to look at the log to know for certain the secret key is working).

Reference

true
Localtabgroup
Localtab live
active
Expand
titleBeans

Name

Type

Description

shibboleth.unlock-keys.KeyStrategies

Collection<DataSealerKeyStrategy>

Enumerates the key strategy beans used to supply secret key(s) to the IdP that should be unlocked by the flow

shibboleth.unlock-keys.Credentials

Collection<MutableCredential>

Enumerates the public key credentials that need to have an unlocked private key injected from the shibboleth.unlock-keys.PrivateKeys bean

shibboleth.unlock-keys.PrivateKeys

Collection<Resource>

Enumerates the resources containing private keys to unlock and inject into the credentials from the shibboleth.unlock-keys.Credentials bean

localtab-live
Expand
titleProperties (V4.1+)

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

Name

Default

Description

idp.unlock-keys.logging

UnlockKeys

Audit log identifier for flow

idp.unlock-keys.accessPolicy

AccessDenied

Name of access control policy for request authorization

idp.unlock-keys.authenticated

true

Whether authentication should be performed prior to access control evaluation

idp.unlock-keys.nonBrowserSupported

false

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

idp.unlock-keys.resolveAttributes

false

Whether attributes should be resolved prior to access control evaluation

localtab-live
Expand
titleFlow Descriptor XML (V4.1+)

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

Code Block
languagexml
<util:list id="shibboleth.AvailableAdminFlows">
 
    <bean parent="shibboleth.OneTimeAdminFlow"
        c:id="http://shibboleth.net/ns/profiles/unlock-keys"
        p:loggingId="%{idp.unlock-keys.logging:UnlockKeys}"
        p:policyName="%{idp.unlock-keys.accessPolicy:AccessDenied}"
        p:nonBrowserSupported="%{idp.unlock-keys.nonBrowserSupported:false}"
        p:authenticated="%{idp.unlock-keys.authenticated:true}"
        p:resolveAttributes="%{idp.unlock-keys.resolveAttributes:false}" />
 
</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.

...