Page tree
Skip to end of metadata
Go to start of metadata

This interface provides a mechanism managing the Account Lockout feature supported by the Password login flow. It allows querying the state of an account, incrementing the lockout count (which could be used to lockout an account administratively), and clearing a lockout.

This is exposed via a simple REST API via an administrative flow located at the path /idp/profile/admin/lockout and access is blocked by default. Like all administrative features, you have the ability to customize authentication and access control.

To the base path you must append a slash, the name of a bean implementing the AccountLockoutManager interface, another slash, and finally the "key" that identifies the lockout record to access. By default this will be a username, a bang (!), and an IP address (unless you customize the way the lockout is scoped).

The default location of the lockout manager bean that is commented out by default is inside the password-authn-config.xml file. If you need to make use of this management API, move that bean (or copy it if you prefer) into global.xml so that it will be accessible to this feature.

Three HTTP methods are supported:

  1. GET – query an account to see if it's locked or not
  2. POST – increment an account's lockout counter artificially
  3. DELETE – clear an account's lockout state

The POST/DELETE operations return a 204 on success, while the GET operation returns a JSON response describing the object queried and the lockout status. An example trace follows (much of the response header dump is elided, this just shows the basics).

Example lockout operations
$ curl -ik "https://localhost/idp/profile/admin/lockout/shibboleth.authn.Password.AccountLockoutManager/jdoe%21192.168.1.1"

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "data" : {
    "type" : "lockout-statuses",
    "id" : "shibboleth.authn.Password.AccountLockoutManager/jdoe!192.168.1.1",
    "attributes" : {
      "lockout" : true
    }
  }
}

$ curl -X DELETE -ik "https://localhost/idp/profile/admin/lockout/shibboleth.authn.Password.AccountLockoutManager/jdoe%21192.168.1.1"
HTTP/1.1 204 No Content

Reference

V4.0 and upgraded systems include a bean defined in conf/admin/general-admin.xml to control aspects of the flow's behavior.

V4.1 includes properties to control various aspects of the flow's behavior using an internally-defined bean that may be overridden if required.

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

Property Default Description
idp.lockout.logging Lockout Audit log identifier for flow
idp.lockout.accessPolicy AccessDenied Name of access control policy for request authorization
idp.lockout.authenticated false Whether authentication should be performed prior to access control evaluation
idp.lockout.nonBrowserSupported false Whether the flow should allow for non-browser clients during authentication
idp.lockout.resolveAttributes false 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/lockout"
        p:loggingId="%{idp.lockout.logging:Lockout}"
        p:policyName="%{idp.lockout.accessPolicy:AccessDenied}"
        p:nonBrowserSupported="%{idp.lockout.nonBrowserSupported:false}"
        p:authenticated="%{idp.lockout.authenticated:false}"
        p:resolveAttributes="%{idp.lockout.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.

  • No labels