--- title: Authenticate users description: IDM stores two types of users in its repository—internal users and managed users. component: pingidm version: 8.1 page_id: pingidm:auth-guide:authenticating-users canonical_url: https://docs.pingidentity.com/pingidm/8.1/auth-guide/authenticating-users.html keywords: ["Authentication", "Internal Users", "Users"] section_ids: authentication-attributes: Attributes used for authentication managing-internal-users: Internal users change-default-admin-pwd: Change the administrator user password --- # 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`, and `idm-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, the `openidm-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 is `openidm-admin`. In production environments, you should change this password, as described in [Change the Administrator User Password](#change-default-admin-pwd). 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. The default password for the `anonymous` user is `anonymous`. * 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: ```json ... "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: ```json { "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: ```json { "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 `internal/user` endpoint as follows: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/internal/user?_queryFilter=true&fields=_id" { "result": [ { "_id": "openidm-admin", "_rev": "00000000ec996921" }, { "_id": "anonymous", "_rev": "00000000d95a68b1" }, { "_id": "idm-provisioning", "_rev": "00000000817e3805" }, { "_id": "connector-server-client", "_rev": "000000003f2a3a85" } ], ... } ``` 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" \ --request GET \ "http://localhost:8080/openidm/internal/user/openidm-admin" { "_id": "openidm-admin", "_rev": "00000000ec996921" } ``` 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](admin-users.html). ## 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: ```json { "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`: ```properties openidm.admin.password=openidm-admin ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Storing secrets and passwords directly in configuration and property files is [deprecated](../release-notes/deprecated-functionality.html#deprecation-secrets-in-config). Use [Secret stores](../security-guide/secret-stores.html) for secret resolution. | 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. > **Collapse: Show me how** > > 1. 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 > }, > ... > ] > } > } > ``` > > 2. Change the `password` field of this `STATIC_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": "var augmentYield = require('auth/customAuthz').setProtectedAttributes(security);require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, 'privileges', 'privilegeAssignments', augmentYield);" > }, > "queryId": "credential-query", > "queryOnResource": "{managed_user}", > "propertyMapping": { > "authenticationId": "username", > "userCredential": "password", > "userRoles": "authzRoles" > }, > "defaultUserRoles": [ > "internal/role/openidm-authorized" > ] > }, > "enabled": true > } > ] > } > }' \ > "{secureHostname}/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": "var augmentYield = require('auth/customAuthz').setProtectedAttributes(security);require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, 'privileges', 'privilegeAssignments', augmentYield);" > }, > "queryId": "credential-query", > "queryOnResource": "managed/user", > "propertyMapping": { > "authenticationId": "username", > "userCredential": "password", > "userRoles": "authzRoles" > }, > "defaultUserRoles": [ > "internal/role/openidm-authorized" > ] > }, > "enabled": true > } > ] > } > } > ```