OpenIDM provides a simple, yet flexible authentication and authorization mechanism based on REST interface URLs and on roles stored in the repository.
OpenIDM distinguishes between internal users and managed users.
Two internal users are created by default - anonymous
and openidm-admin. These accounts are separated from
other user accounts to protect them from any reconciliation or
synchronization processes.
OpenIDM stores internal users and their role membership in a table
in the repository called internaluser when implemented
in MySQL, and in the internal_user table for an OrientDB
repository. You can add or remove internal users over the REST interface
(at http://localhost:8080/openidm/repo/internal/user) or
directly in the repository.
This user serves to access OpenIDM anonymously, for users who do not have their own accounts. The anonymous user is primarily intended to allow self-registration.
OpenIDM stores the anonymous user's password,
anonymous, in clear text in the repository internal
user table. The password is not considered to be secret.
This user serves as the super administrator. After
installation, the openidm-admin user has full access,
and provides a fallback mechanism in case other users are locked out. Do
not use openidm-admin for normal tasks. Under normal
circumstances, no real user is associated with the
openidm-admin user account, so audit log records that
pertain to openidm-admin do not reflect the actions of
any real person.
OpenIDM encrypts the password, openidm-admin, by
default. Change the password immediately after installation. For
instructions, see To Replace the Default User and Password.
External users that OpenIDM manages are referred to as managed users.
When implemented in MySQL, OpenIDM stores managed users in the managed
objects table of the repository, named managedobjects.
A second MySQL table, managedobjectproperties, serves as
the index table. When implemented in OrientDB, managed objects are stored in
the table managed_user.
By default, the attribute names for managed user login and password
are userName and password,
respectively.
OpenIDM does not allow access to the REST interface unless you
authenticate. If a project requires anonymous access, to allow users to
self-register for example, then allow access by user
anonymous, password anonymous, as
described in Section 13.1.1, “Internal Users”. In production, only
applications are expected to access the REST interface.
OpenIDM supports an improved authentication mechanism on the REST interface. Unlike basic authentication or form-based authentication, the OpenIDM authentication mechanism is compatible with the AJAX framework.
$ curl --user userName:password
This authentication is compatible with standard basic authentication, except that it will not prompt for credentials if they are missing in the request.
$ curl --header "X-OpenIDM-Username: openidm-admin" --header "X-OpenIDM-Password: openidm-admin"
For more information about the OpenIDM authentication mechanism, see Use Message Level Security.
You can change the attributes that OpenIDM uses to store user login
and password values. The attribute names are shown in a database query
that is defined in
openidm/conf/repo..
repo-type.json
Two queries are defined by default.
credential-internaluser-queryUses the _openidm_id attribute for login
credential-queryUses the userName attribute for login
The openidm/conf/authentication.json file defines
the currently active query as the value of the queryId
property. In the following example, credential-query is
active.
{
"queryId" : "credential-query",
"queryOnResource" : "managed/user",
"defaultUserRoles" : [ ]
}You can explicitly define the properties that constitute passwords or
roles by setting the propertyMapping object in the
conf/authentication.json file. By default, the property
mapping is configured as follows:
...
"propertyMapping" : {
"userId" : "_id",
"userCredential" : "password",
"userRoles" : "roles"
},
...
OpenIDM sets up the following roles by default:
Role for users accessing OpenIDM with the default anonymous account
OpenIDM administrator role
Default role for any user authenticated with a user name and password
Default role for any user authenticated with mutual SSL authentication
A user's roles are fetched after authentication.
If no roles are defined in the user profile, the
defaultUserRoles are applied. You can configure
the default roles that are assigned to successfully authenticated users by
setting the defaultUserRoles property in
openidm/conf/authentication.json, which
takes a list. The default value is openidm-authorized.
{
"queryId": "credential-query",
"queryOnResource": "managed/user",
"defaultUserRoles": [
"openidm-authorized"
]
}A managed user who does not have a role of openidm-authorized
can authenticate but is unable to access certain system resources,
according to the access control configured in the access.js
file. Requests on a resource for which access is denied return a 403 error.
For more information, see the following section covering
Section 13.4, “Authorization”.
OpenIDM provides role-based authorization that restricts direct
HTTP access to REST interface URLs. The default authorization configuration
grants different access rights to users that are assigned the roles
"openidm-admin", "openidm-cert",
"openidm-authorized", and "openidm-reg".
Note that this access control applies to direct HTTP calls only. Access for internal calls (for example, calls from scripts) is not affected by this mechanism.
Authorization is configured in two script files:
openidm/bin/defaults/script/router-authz.js
openidm/script/access.js
OpenIDM calls these scripts for each request, via the
onRequest hook that is defined in the default
router.json file. The scripts either throw the string
Access denied, or nothing. If
Access denied is thrown, OpenIDM denies the request.
This file provides the functions that enforce access rules. For example, the following function controls whether users with a certain role can start a specified process.
...
function isAllowedToStartProcess() {
var processDefinitionId = request.value._processDefinitionId;
return isProcessOnUsersList(processDefinitionId);
}
...
There are certain functions in router-authz.js
that should not be altered. These are indicated in the
file itself.
This file defines the access configuration for HTTP requests and
references the methods defined in router-authz.js. Each
entry in the configuration contains a pattern to match against the incoming
request ID, and the associated roles, methods, and actions that are allowed
for requests on that pattern.
The following sample configuration entry indicates the configurable parameters and their purpose.
{
"pattern" : "*",
"roles" : "openidm-admin",
"methods" : "*", // default to all methods allowed
"actions" : "*", // default to all actions allowed
"customAuthz" : "disallowQueryExpression()",
"excludePatterns": "system/*"
},
The overall intention of this entry is to allow users with the role
openidm-admin HTTP access to everything except the
system endpoints. The parameters are as follows:
"pattern" - the REST endpoint to which access
is being controlled. "*" indicates access to all
endpoints. "managed/user/*" would indicate access
to all managed user objects.
"roles" - a comma-separated list of the roles
to which this access configuration applies.
"methods" - a comma separated list of the
methods to which access is being granted. The method can be one or
more of create, read, update, delete, patch, action, query.
A value of "*" indicates that all methods are
allowed. A value of "" indicates that no methods
are allowed.
"actions" - a comma separated list of the
allowed actions. The possible values depend on the service (URL) that
is being exposed. The following list indicates the possible actions
for each service.
openidm/managed -
patch |
openidm/recon -
recon, cancel |
openidm/sync -
onCreate, onUpdate, onDelete, recon, performAction
|
openidm/external/email -
(no action parameter applies) |
openidm/external/rest -
(no action parameter applies) |
openidm/authentication -
reauthenticate |
openidm/system -
createconfiguration |
openidm/system/* -
script |
openidm/taskscanner -
execute, cancel |
openidm/workflow/processinstance -
(no action parameter applies) |
openidm/workflow/taskinstance -
claim,complete |
A value of "*" indicates that all actions
exposed for that service are allowed. A value of ""
indicates that no actions are allowed.
"customAuthz" - an optional parameter that
enables you to specify a custom function for additional authorization
checks. These functions are defined in router-authz.js
.
The allowedPropertiesForManagedUser variable,
declared at the beginning of the file, enables you to create a white
list of attributes that users may modify on their own accounts.
"excludePatterns" - an optional parameter
that enables you to specify particular endpoints to which access
should not be given.