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) 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
|
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) findUsers(params) → {boolean}
Search for users matching the specified query.
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON with the parameters. Properties
|
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
|
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
|
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) modifyProfile(params) → {object}
This function retrieves the profile of a user and updates it.
Parameters:
Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON parameters. Properties
|
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
|
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
|
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']);