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
|
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
|
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) createUser(params)
Creates user from passed parameters.
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON parameters. Properties
|
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) findPrincipals(params) → {object}
Search for principals matching the specified criteria.
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON parameters. Properties
|
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) 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) getUser() → {object}
Returns the logged-in user. If not logged-in, this will return undefined.
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
|
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
|
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) modifyUser(params) → {object}
Retrieves the user specified and updates it with the changes applied.
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON parameters. Properties
|
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']);