auth

Built-in authentication functions.

Example
var authLib = require('/lib/xp/auth');

Methods

(static) addMembers(principalKey, members)

Adds members to a principal (user or role).

Parameters:
Name Type Description
principalKey string

Key of the principal to add members to.

members string

Keys of the principals to add.

Example
// Add members to specified principal.
authLib.addMembers('role:roleId', ['user:mystore:user1', 'group:mystore:group1']);

(static) changePassword(params)

Changes password for specified user.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Description
userKey string

Key for user to change password.

password string

New password to set.

Example
// Find current logged-in user.
var user = authLib.getUser();

// Change password for the user.
authLib.changePassword({
    userKey: user.key,
    password: 'new-secret-password'
});

(static) createGroup(params)

Creates a group.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Description
userStore string

Key for user store where group has to be created.

name string

Group name.

displayName string

Group display name.

description string

as principal description .

Examples
// Creates a group.
var group = authLib.createGroup({
    userStore: 'myUserStore',
    name: 'groupName',
    displayName: 'Group display name',
    description: "description"
});
// Information about the created group.
var expected = {
    "type": "group",
    "key": "group:system:group-a",
    "displayName": "Group A",
    "modifiedTime": "1970-01-01T00:00:00Z",
    "description": "description"
};

(static) createRole(name)

Creates a role.

Parameters:
Name Type Description
name string

Role name.

params.displayName string

Role display name.

params.description string

as principal description .

Examples
// Creates a group.
var role = authLib.createRole({
    name: 'aRole',
    displayName: 'Role Display Name',
    description: 'description'
});
// Information about the created group.
var expected = {
    'type': 'role',
    'key': 'role:aRole',
    'displayName': 'Role Display Name',
    'modifiedTime': '1970-01-01T00:00:00Z',
    'description': 'description'
};

(static) createUser(params)

Creates user from passed parameters.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Attributes Description
userStore string

Key for user store where user has to be created.

name string

User login name to set.

displayName string

User display name.

email string <optional>

User email.

Examples
// Creates a user.
var user = authLib.createUser({
    userStore: 'myUserStore',
    name: 'userName',
    displayName: 'User display name',
    email: 'userName@enonic.com'
});
// Information when creating a user.
var expected = {
    "type": "user",
    "key": "user:enonic:user1",
    "displayName": "User 1",
    "modifiedTime": "1970-01-01T00:00:00Z",
    "disabled": false,
    "email": "user1@enonic.com",
    "login": "user1",
    "userStore": "enonic"
};

(static) deletePrincipal(principalKey) → {boolean}

Deletes the principal with the specified key.

Parameters:
Name Type Description
principalKey string

Principal key to delete.

Returns:

True if deleted, false otherwise.

Type
boolean
Examples
// Returns the principal information for specified principal key.
var deleted = authLib.deletePrincipal('user:myUserStore:userId');
// Information when getting a principal.
var expected = true;

(static) findPrincipals(params) → {object}

Search for principals matching the specified criteria.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Attributes Description
type string <optional>

Principal type to look for, one of: 'user', 'group' or 'role'. If not specified all principal types will be included.

userStore string <optional>

Key of the user store to look for. If not specified all user stores will be included.

start string <optional>

First principal to return from the search results. It can be used for pagination.

count string <optional>

A limit on the number of principals to be returned.

name string <optional>

Name of the principal to look for.

searchText string <optional>

Text to look for in any principal field.

Returns:

The "total" number of principals matching the search, the "count" of principals included, and an array of "hits" containing the principals.

Type
object
Examples
// Find principals with the specified name.
var result = authLib.findPrincipals({
    type: 'user',
    userStore: 'user-store',
    start: 0,
    count: 10,
    name: 'user1'
});
// Result for finding principals.
var expected = {
    "total": 3,
    "count": 3,
    "hits": [
        {
            "type": "group",
            "key": "group:system:group-a",
            "displayName": "Group A",
            "modifiedTime": "1970-01-01T00:00:00Z",
            "description": "description"
        },
        {
            "type": "role",
            "key": "role:aRole",
            "displayName": "Role Display Name",
            "modifiedTime": "1970-01-01T00:00:00Z",
            "description": "description"
        },
        {
            "type": "user",
            "key": "user:enonic:user1",
            "displayName": "User 1",
            "modifiedTime": "1970-01-01T00:00:00Z",
            "disabled": false,
            "email": "user1@enonic.com",
            "login": "user1",
            "userStore": "enonic"
        }
    ]
};

(static) findUsers(params) → {boolean}

Search for users matching the specified query.

Parameters:
Name Type Description
params object

JSON with the parameters.

Properties
Name Type Attributes Default Description
start number <optional>
0

Start index (used for paging).

count number <optional>
10

Number of contents to fetch.

query string

Query expression.

sort string <optional>

Sorting expression.

includeProfile boolean <optional>
false

Include profile.

Returns:

Result of query.

Type
boolean
Examples
// Find users with the specified email.
var result = authLib.findUsers({
    start: 0,
    count: 1,
    query: "email = 'user1@enonic.com'",
    sort: "modifiedTime DESC",
    includeProfile: true
});
// Result for finding principals.
var expected = {
    "total": 1,
    "count": 1,
    "hits": [
        {
            "type": "user",
            "key": "user:enonic:user1",
            "displayName": "User 1",
            "modifiedTime": "1970-01-01T00:00:00Z",
            "disabled": false,
            "email": "user1@enonic.com",
            "login": "user1",
            "userStore": "enonic",
            "profile": {
                "myApp": {
                    "subString": "subStringValue",
                    "subLong": 123
                },
                "string": "stringValue"
            }
        }
    ]
};

(static) generatePassword() → {string}

Generates a secure password.

Returns:

A secure generated password.

Type
string
Example
// Generate a password and returns the password string.
var pwd = authLib.generatePassword();
log.info('New password: %s', pwd);

(static) getIdProviderConfig() → {object}

This function returns the ID provider configuration for the current user store. It is meant to be called from an ID provider controller.

Returns:

The ID provider configuration for current user store as JSON.

Type
object
Examples
var result = authLib.getIdProviderConfig();
log.info('Field value for the current ID provider config = %s', result.Field);
// ID Provider config returned.
var expected = {
    "set": {
        "subString": "subStringValue",
        "subLong": 123
    },
    "string": "stringValue"
};

(static) getMembers(principalKey) → {Array.<object>}

Returns a list of principals that are members of the specified principal.

Parameters:
Name Type Description
principalKey string

Principal key to retrieve members for.

Returns:

Returns the list of principals.

Type
Array.<object>
Examples
// Returns all members for specified principal key.
var members = authLib.getMembers('group:system:group-a');
// Information when getting a principal.
var expected = [
    {
        "type": "user",
        "key": "user:enonic:user1",
        "displayName": "User 1",
        "modifiedTime": "1970-01-01T00:00:00Z",
        "disabled": false,
        "email": "user1@enonic.com",
        "login": "user1",
        "userStore": "enonic"
    },
    {
        "type": "user",
        "key": "user:enonic:user2",
        "displayName": "User 2",
        "modifiedTime": "1970-01-01T00:00:00Z",
        "disabled": false,
        "email": "user2@enonic.com",
        "login": "user2",
        "userStore": "enonic"
    }
];

(static) getMemberships(principalKey) → {Array.<object>}

Returns a list of principals the specified principal is a member of.

Parameters:
Name Type Description
principalKey string

Principal key to retrieve memberships for.

Returns:

Returns the list of principals.

Type
Array.<object>
Examples
// Returns all memberships for specified principal key.
var memberships = authLib.getMemberships('user:myUserStore:userId');
// Information when getting a principal.
var expected = [
    {
        "type": "role",
        "key": "role:aRole",
        "displayName": "Role Display Name",
        "modifiedTime": "1970-01-01T00:00:00Z",
        "description": "description"
    },
    {
        "type": "group",
        "key": "group:system:group-a",
        "displayName": "Group A",
        "modifiedTime": "1970-01-01T00:00:00Z",
        "description": "description"
    }
];

(static) getPrincipal(principalKey) → {object}

Returns the principal with the specified key.

Parameters:
Name Type Description
principalKey string

Principal key to look for.

Returns:

the principal specified, or null if it doesn't exist.

Type
object
Examples
// Returns the principal information for specified principal key.
var principal = authLib.getPrincipal('user:myUserStore:userId');
// Information when getting a principal.
var expected = {
    "type": "user",
    "key": "user:enonic:user1",
    "displayName": "User 1",
    "modifiedTime": "1970-01-01T00:00:00Z",
    "disabled": false,
    "email": "user1@enonic.com",
    "login": "user1",
    "userStore": "enonic"
};

(static) getProfile(params) → {object}

This function retrieves the profile of a user.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Attributes Description
key string

Principal key of the user.

scope string <optional>

Scope of the data to retrieve.

Returns:

The extra data as JSON

Type
object
Examples
// Returns the profile of user1 for myapp
var profile = authLib.getProfile({
    key: "user:enonic:user1"
});
// Information when retrieving a profile.
var expectedProfile = {
    "myApp": {
        "subString": "subStringValue",
        "subLong": 123
    },
    "string": "stringValue"
};
// Returns the profile of user1 for myapp
var scopedProfile = authLib.getProfile({
    key: "user:enonic:user1",
    scope: "myApp"
});
// Information when retrieving a profile.
var expectedScopedProfile = {
    "subString": "subStringValue",
    "subLong": 123
};

(static) getUser(paramsopt) → {object}

Returns the logged-in user. If not logged-in, this will return undefined.

Parameters:
Name Type Attributes Description
params object <optional>

JSON parameters.

Properties
Name Type Attributes Default Description
includeProfile boolean <optional>
false

Include profile.

Returns:

Information for logged-in user.

Type
object
Examples
// Returns the current loggedin user.
var user = authLib.getUser();

if (user) {
    log.info('User logged in: %s', user.displayName);
}
// Information when retrieving a user.
var expected = {
    "type": "user",
    "key": "user:enonic:user1",
    "displayName": "User 1",
    "modifiedTime": "1970-01-01T00:00:00Z",
    "disabled": false,
    "email": "user1@enonic.com",
    "login": "user1",
    "userStore": "enonic"
};

(static) hasRole(role) → {boolean}

Checks if the logged-in user has the specified role.

Parameters:
Name Type Description
role string

Role to check for.

Returns:

True if the user has specfied role, false otherwise.

Type
boolean
Example
// Checks if the user has the specified role.
var flag = authLib.hasRole('system.admin.login');

log.info('The user ' + (flag ? 'has' : 'does not have') +
         ' access to the admin console.');

(static) login(params) → {object}

Login a user with the specified userStore, userName and password.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Attributes Default Description
user string

Name of user to log in.

userStore string <optional>

Name of user-store where the user is stored. If not specified it will try all available user-stores, in alphabetical order.

password string <optional>

Password for the user. Ignored if skipAuth is set to true, mandatory otherwise.

skipAuth boolean <optional>
false

Skip authentication.

sessionTimeout number <optional>

Session timeout (in seconds). By default, the value of session.timeout from com.enonic.xp.web.jetty.cfg

Returns:

Information for logged-in user.

Type
object
Examples
// Login with a explicit user store.
var result1 = authLib.login({
    user: 'user1@enonic.com',
    password: 'secret',
    userStore: 'enonic'
});

if (result1.authenticated) {
    log.info('User logged in: %s', result1.user.displayName);
}
// Login to any of the user stores, in sequence.
var result2 = authLib.login({
    user: 'user1@enonic.com',
    password: 'secret',
    userStore: ['enonic', 'vip']
});
// Login to any of the existing user stores.
var result3 = authLib.login({
    user: 'user1@enonic.com',
    password: 'secret'
});
// Login with a explicit user store without authentication.
var result4 = authLib.login({
    user: 'user1@enonic.com',
    userStore: 'enonic',
    skipAuth: true
});
// Result of a successful login operation.
var expected = {
    "authenticated": true,
    "user": {
        "type": "user",
        "key": "user:enonic:user1",
        "displayName": "User 1",
        "modifiedTime": "1970-01-01T00:00:00Z",
        "disabled": false,
        "email": "user1@enonic.com",
        "login": "user1",
        "userStore": "enonic"
    }
};

(static) logout()

Logout an already logged-in user.

Example
// Logout the current user.
authLib.logout();

(static) modifyGroup(params) → {object}

Retrieves the group specified and updates it with the changes applied.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Description
key string

Principal key of the group to modify.

editor function

Group editor function to apply to group.

Returns:

the updated group.

Type
object
Examples
// Callback to edit the group.
function editor(c) {
    c.displayName = 'Modified display name';
    c.description = 'descriptionX';
    return c;
}

// Modify group with specified key.
var group = authLib.modifyGroup({
    key: 'group:enonic:groupId',
    editor: editor
});
// Information about the modified group.
var expected = {
    "type": "group",
    "key": "group:system:group-a",
    "displayName": "Modified display name",
    "modifiedTime": "1970-01-01T00:00:00Z",
    "description": "descriptionX"
};

(static) modifyProfile(params) → {object}

This function retrieves the profile of a user and updates it.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Attributes Description
key string

Principal key of the user.

scope string <optional>

Scope of the data to retrieve and update.

editor function

Profile editor function to apply.

Returns:

The extra data as JSON

Type
object
Examples
// Callback to edit the user profile.
function editor(c) {
    if (!c) {
        c = {};
    }
    c.newField = "New field";
    return c;
}

// Modify the profile of user1 for myapp
var profile = authLib.modifyProfile({
    key: "user:enonic:user1",
    scope: "myApp",
    editor: editor
});
// Information about the modified profile.
var expected = {
    "subString": "subStringValue",
    "subLong": 123,
    "newField": "New field"
};

(static) modifyRole(params) → {object}

Retrieves the role specified and updates it with the changes applied.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Description
key string

Principal key of the role to modify.

editor function

Role editor function to apply to role.

Returns:

the updated role.

Type
object
Examples
// Callback to edit the role.
function editor(c) {
    c.displayName = 'Modified display name';
    c.description = 'descriptionX';
    return c;
}

// Modify role with specified key.
var role = authLib.modifyRole({
    key: 'role:aRole',
    editor: editor
});
// Information about the modified role.
var expected = {
    'type': 'role',
    'key': 'role:aRole',
    'displayName': 'Modified display name',
    'modifiedTime': '1970-01-01T00:00:00Z',
    'description': 'descriptionX'
};

(static) modifyUser(params) → {object}

Retrieves the user specified and updates it with the changes applied.

Parameters:
Name Type Description
params object

JSON parameters.

Properties
Name Type Description
key string

Principal key of the user to modify.

editor function

User editor function to apply to user.

Returns:

the updated user.

Type
object
Examples
// Callback to edit the user.
function editor(c) {
    c.displayName = 'Modified display name';
    c.email = "new_email@enonic.com";
    return c;
}

// Modify user with specified key.
var user = authLib.modifyUser({
    key: 'user:enonic:userId',
    editor: editor
});
// Information about the modified user.
var expected = {
    "type": "user",
    "key": "user:enonic:user1",
    "displayName": "Modified display name",
    "modifiedTime": "1970-01-01T00:00:00Z",
    "disabled": false,
    "email": "new_email@enonic.com",
    "login": "user1",
    "userStore": "enonic"
};

(static) removeMembers(principalKey, members)

Removes members from a principal (user or role).

Parameters:
Name Type Description
principalKey string

Key of the principal to remove members from.

members string

Keys of the principals to remove.

Example
// Remove members from specified principal.
authLib.removeMembers('role:roleId', ['user:mystore:user1', 'group:mystore:group1']);