rb:authenticate

Apply password protection for a page

Body

The rb:authenticate body can contain any other XML markup.

Attributes

Remarks

The authenticate tag regulates HTTP authentication methods.

This tag allows an integration partner to 'protect' either an entire page or a subsection of a page such that it can only be seen by authorised people. The tag is used to surround an XML subtree - which typically comprises the entire document. When the Presentation Engine encounters this tag it looks for a 'Authorization' HTTP header. If the header is not found then the server returns a 'Autorization Failed' response (code 401) to the web browser, which will in turn cause the browser to prompt for username and password.

In order to send the authorization failed the Presentation Engine must specify a 'domain'. This is simply a text string that is displayed by the browser in the login form automatically displayed. If the domain is not specified the Presentation Engine will generate an error.

If the 'Authorization' header is present then the Presentation Engine extracts the browser provided username and password and validates these values against the specified 'community' (mandatory XML attribute for this tag). Validation makes use of user information held in the contacts template. Specifically the Presentation Engine makes a call to rb.contact.validate().

The 'community' parameter is used to identify the set of people against which the username and password are to be validated. This may select a Community, a single individual or an OU (Organisational Unit). 

The behaviour of the tag depends on the value of the 'mandatory' attribute. This takes a value of 'yes' or 'no', the default if the attribute is absent is 'yes'.

mandatory='yes' (default)

If mandatory is 'yes' then the browser provided username and password must match against a member of the specified community. If it doesn't then the section of XML contained within the tag is not executed.

mandatory='no'

If 'mandatory' is no then the XML subtree is executed anyway - allowing the Pattern Page to programmatically deal with the error. An example would be a page that requires a username and password but that if it doesn't get one it presents the user with a self registration page.

In order for the integration partner to programmatically deal with this situation the Presentation Engine makes the values provided by the user available through the Redbourne Object Model via the system template methods under rb.security