ID Providers
Contents
ID Providers
The XP framework supports pluggable authentication using a concept called IDproviders
Introduction
As part of the XP IAM (Identity and Access management) apps and sites may be loosely associated with an IDprovider. This section describes how to implement an ID provider application.
When an IDprovider is active throughout the http request pipeline, it may intercept or process the request to dynamically provide authentication.
Descriptor
An ID provider application requires a descriptor file. The descriptor should be placed in your project as src/main/resources/idprovider/idprovider.xml
.
<id-provider>
<mode>LOCAL</mode> (1)
<form> (2)
<input name="title" type="TextLine">
<label>Title</label>
<occurrences minimum="0" maximum="1"/>
<default>User Login</default>
</input>
</form>
</id-provider>
1 | mode specifies how users and groups are process and stored in XP. Allowed values are:
|
||
2 | form defines config options that can be defined from the UI when setting up ID providers. Forms are based on the schema system
|
idprovider.js
To turn an app into an ID provider, you must add a specific idprovier JavaScript file src/main/resources/idprovider/idprovider.js
to the application. An app can only implement a single ID provider.
idprovider.js can export a range of different pre defined functions to implement different functionality: * As a controller - for instance by rendering a login page, or logging out the user * As a filter - by processing every request automatically log in users * As an error handler - intercepting 401 (Unauthorised) errors from the request pipeline
The example below demonstrates a typical idprovider script may be implemented
var authLib = require('/lib/xp/auth');
// Filter every reqeust
exports.autoLogin = function (req) {
log.info('Invoked only unless user is already authenticated');
};
// Override error handler when authentication is required
exports.handle401 = function (req) {
var body = generateLoginPage();
return {
status: 401,
contentType: 'text/html',
body: body
};
};
// Triggered when user visits the ID providers login endpoint
exports.login = function (req) {
var redirectUrl = req.validTicket ? req.params.redirect : undefined;
var body = generateLoginPage(redirectUrl);
return {
contentType: 'text/html',
body: body
};
};
// Triggered when user visits the ID providers logout endpoint
exports.logout = function (req) {
// Sign user out of XP
authLib.logout();
var redirectUrl = req.validTicket ? req.params.redirect : undefined;
if (redirectUrl) {
return {
redirect: redirectUrl
};
} else {
var body = generateLoginPage();
return {
contentType: 'text/html',
body: body
};
}
};
If the "login" or "logout" endpoints all called with a "redirect" parameter, a validation of the origin is performed. The result of this validation is then passed to the ID Provider as a request property "validTicket". |