Authenticate Users
IDM stores two types of users in its repository—internal users and managed users.
- Internal users
Internal users are special user accounts that are stored separately from regular users to protect them from any reconciliation or synchronization processes. When IDM first starts up, it creates three internal users in the repository by default—
openidm-admin
,anonymous
, andidm-provisioning
:- openidm-admin
This user serves as the top-level administrator and has full access to all IDM resources. This account provides a fallback mechanism in the event that other users are locked out of their accounts. Do not use
openidm-admin
for regular tasks. Under normal circumstances, theopenidm-admin
account does not represent a regular user, so audit log records for this account do not represent the actions of any real person.The default password for the
openidm-admin
user isopenidm-admin
. In production environments, you should change this password, as described in "Change the Administrator User Password". The new password is symmetrically encrypted as it is changed.- anonymous
This user enables anonymous access to IDM. It is used to interact with IDM in limited ways without further authentication, such as when a user has not yet logged in and makes a login request. The anonymous user account also allows self-registration. For more information about self-registration, see Self-Registration.
The default password for the
anonymous
user isanonymous
.- idm-provisioning
The internal user
idm-provisioning
is a service account used by AM to provision accounts in IDM. It has no password, and isn't meant to be logged in directly. If you are not planning to use AM and IDM together as a platform, you can safely remove this user.
- Managed users
Regular user accounts that are stored in IDM's repository are called managed users because IDM effectively manages these accounts.
Both internal and managed users must authenticate to gain access to the server. The way in which these user types are authenticated is defined in your project's conf/authentication.json
file.
Any request to IDM will authenticate the user and return a token. To improve tracing through logs, authenticate internal and managed users over REST by sending a POST request to the openidm/authentication
endpoint, with _action=login
. The following example authenticates the openidm-admin
user:
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--cacert ca-cert.pem \
--request POST \
"https://localhost:8443/openidm/authentication?_action=login"
Attributes Used For Authentication
By default, the attribute names that are used to authenticate managed and internal users are username
and password
. You can change the attributes that store authentication information with the propertyMapping
object in the conf/authentication.json
file. The following excerpt of the authentication.json
file shows the default authentication attributes:
... "propertyMapping" : { "authenticationId" : "username", "userCredential" : "password", "userRoles" : "authzRoles" }, ...
If you change the attributes that are used for authentication, you must also change any authentication queries that use those attributes. The following authentication queries are referenced in authentication.json
:
credential-internaluser-query
authenticates internal users.credential-query
authenticates managed users.for-username
To change the authentication queries for a customized authentication attribute, create a queryFilters.json
file in your project's conf
directory. Include the authentication query IDs and the amended query filter, taking into account your changed attributes. The default authentication queries are as follows:
{ "credential-query": { "_queryFilter": "/userName eq \"${username}\" AND /accountStatus eq \"active\"" }, "credential-internaluser-query": { "_queryFilter": "/_id eq \"${username}\"" }, "for-userName": { "_queryFilter": "/userName eq \"${uid}\"" } }
The following example conf/queryFilters.json
file shows the authentication queries adjusted to use the email
attribute instead of the username
attribute:
{ "credential-query": { "_queryFilter": "/email eq \"${email}\" AND /accountStatus eq \"active\"" }, "credential-internaluser-query": { "_queryFilter": "/_id eq \"${email}\"" }, "for-userName": { "_queryFilter": "/email eq \"${uid}\"" } }
Internal Users
Although internal users are considered to be special user accounts, you can manage them over the REST interface as you would any regular user in the repository.
To list the internal users over REST, query the repo
endpoint as follows:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --cacert ca-cert.pem \ --request GET \ "https://localhost:8443/openidm/internal/user?_queryFilter=true&fields=_id"
{ "result": [ { "_id": "openidm-admin", "_rev": "00000000ef9f6b13" }, { "_id": "anonymous", "_rev": "00000000d6216802" }, { "_id": "idm-provisioning", "_rev": "00000000895c385a" } ], "resultCount": 3, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 }
To query the details of an internal user, include the user ID in the request, for example:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --cacert ca-cert.pem \ --request GET \ "https://localhost:8443/openidm/internal/user/openidm-admin"
{ "_id": "openidm-admin", "_rev": "00000000c7554e13" }
Internal users have specific authorization roles by default. These roles determine what the users can access in IDM. The anonymous
user has only the openidm-reg
role by default. This role grants only the resource access required to log in, register, and so forth. To identify the authorization roles for the openidm-admin
internal user, and for information about creating and managing other administrative users, see "Administrative Users".
Change the Administrator User Password
The password of the openidm-admin
user is openidm-admin
by default. This password is set in the following excerpt of the authentication.json
file:
{ "name" : "STATIC_USER", "properties" : { "queryOnResource" : "internal/user", "username" : "openidm-admin", "password" : "&{openidm.admin.password}", "defaultUserRoles" : [ "internal/role/openidm-authorized", "internal/role/openidm-admin" ] }, "enabled" : true }
The password
property references the openidm.admin.password
property, set in resolver/boot.properties
:
openidm.admin.password=openidm-admin
You can change the default administrator password in a number of ways:
Edit the
resolver/boot.properties
file before you start IDM (or restart IDM after you change this file).Set the value directly in the
conf/authentication.json
file.Update the authentication configuration over REST.
Get the current authentication configuration:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --cacert ca-cert.pem \ --request GET \ "https://localhost:8443/openidm/config/authentication"
{ "_id": "authentication", "serverAuthContext": { ... "authModules": [ ... { "name": "STATIC_USER", "properties": { "queryOnResource": "internal/user", "username": "openidm-admin", "password": "&{openidm.admin.password}", "defaultUserRoles": [ "internal/role/openidm-authorized", "internal/role/openidm-admin" ] }, "enabled": true }, ... ] } }
Change the
password
field of thisSTATIC_USER
module and replace the authentication configuration:curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --cacert ca-cert.pem \ --request PUT \ --data '{ "_id": "authentication", "serverAuthContext": { "sessionModule": { "name": "JWT_SESSION", "properties": { "maxTokenLifeMinutes": 120, "tokenIdleTimeMinutes": 30, "sessionOnly": true, "isHttpOnly": true, "enableDynamicRoles": false } }, "authModules": [ { "name": "STATIC_USER", "properties": { "queryOnResource": "internal/user", "username": "anonymous", "password": { "$crypto": { "type": "x-simple-encryption", "value": { "cipher": "AES/CBC/PKCS5Padding", "stableId": "openidm-sym-default", "salt": "xBlTp67ze4Ca5LTocXOpoA==", "data": "mdibV6UabU2M+M5MK7bjFQ==", "keySize": 16, "purpose": "idm.config.encryption", "iv": "36D2+FumKbaUsndNQ+/+5w==", "mac": "ZM8GMnh0n80QwtSH6QsNmA==" } } }, "defaultUserRoles": [ "internal/role/openidm-reg" ] }, "enabled": true }, { "name": "STATIC_USER", "properties": { "queryOnResource": "internal/user", "username": "openidm-admin", "password": "newAdminPassword", "defaultUserRoles": [ "internal/role/openidm-authorized", "internal/role/openidm-admin" ] }, "enabled": true }, { "name": "MANAGED_USER", "properties": { "augmentSecurityContext": { "type": "text/javascript", "source": "require('auth/customAuthz').setProtectedAttributes(security)" }, "queryId": "credential-query", "queryOnResource": "managed/user", "propertyMapping": { "authenticationId": "username", "userCredential": "password", "userRoles": "authzRoles" }, "defaultUserRoles": [ "internal/role/openidm-authorized" ] }, "enabled": true }, { "name": "SOCIAL_PROVIDERS", "properties": { "defaultUserRoles": [ "internal/role/openidm-authorized" ], "augmentSecurityContext": { "type": "text/javascript", "globals": {}, "file": "auth/populateAsManagedUserFromRelationship.js" }, "propertyMapping": { "userRoles": "authzRoles" } }, "enabled": true } ] } }' \ "https://localhost:8443/openidm/config/authentication"
{ "_id": "authentication", "serverAuthContext": { "sessionModule": { "name": "JWT_SESSION", "properties": { "maxTokenLifeMinutes": 120, "tokenIdleTimeMinutes": 30, "sessionOnly": true, "isHttpOnly": true, "enableDynamicRoles": false } }, "authModules": [ { "name": "STATIC_USER", "properties": { "queryOnResource": "internal/user", "username": "anonymous", "password": { "$crypto": { "type": "x-simple-encryption", "value": { "cipher": "AES/CBC/PKCS5Padding", "stableId": "openidm-sym-default", "salt": "xBlTp67ze4Ca5LTocXOpoA==", "data": "mdibV6UabU2M+M5MK7bjFQ==", "keySize": 16, "purpose": "idm.config.encryption", "iv": "36D2+FumKbaUsndNQ+/+5w==", "mac": "ZM8GMnh0n80QwtSH6QsNmA==" } } }, "defaultUserRoles": [ "internal/role/openidm-reg" ] }, "enabled": true }, { "name": "STATIC_USER", "properties": { "queryOnResource": "internal/user", "username": "openidm-admin", "password": { "$crypto": { "type": "x-simple-encryption", "value": { "cipher": "AES/CBC/PKCS5Padding", "stableId": "openidm-sym-default", "salt": "l0trJWBzg5JKcWLzNq8QDA==", "data": "MKAkL9FVEq/FnWq+8a90+QcjfkEbrK7W4tIc3ORD1ck=", "keySize": 16, "purpose": "idm.config.encryption", "iv": "UMjU6crk332MZtEjo+wEmw==", "mac": "7EvTqjpmuS9PmY1aCT2s+g==" } } }, "defaultUserRoles": [ "internal/role/openidm-authorized", "internal/role/openidm-admin" ] }, "enabled": true }, { "name": "MANAGED_USER", "properties": { "augmentSecurityContext": { "type": "text/javascript", "source": "require(auth/customAuthz).setProtectedAttributes(security)" }, "queryId": "credential-query", "queryOnResource": "managed/user", "propertyMapping": { "authenticationId": "username", "userCredential": "password", "userRoles": "authzRoles" }, "defaultUserRoles": [ "internal/role/openidm-authorized" ] }, "enabled": true }, { "name": "SOCIAL_PROVIDERS", "properties": { "defaultUserRoles": [ "internal/role/openidm-authorized" ], "augmentSecurityContext": { "type": "text/javascript", "globals": {}, "file": "auth/populateAsManagedUserFromRelationship.js" }, "propertyMapping": { "userRoles": "authzRoles" } }, "enabled": true } ] } }