--- title: Authentication and session modules description: Configure PingIDM authentication and session modules, including JWT_SESSION, MANAGED_USER, CLIENT_CERT, PASSTHROUGH, and more (IWA and SOCIAL_PROVIDERS deprecated) component: pingidm version: 7.5 page_id: pingidm:auth-guide:auth-session-modules canonical_url: https://docs.pingidentity.com/pingidm/8.1/auth-guide/auth-session-modules.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Authentication", "Sessions", "Internal Users", "Certificates", "Passthrough Authentication", "Social Authentication", "Kerberos"] superseded_by: https://docs.pingidentity.com/pingidm/8.1/auth-guide/auth-session-modules.html section_ids: jwt-session-module: JWT_SESSION authenticate_without_a_session: Authenticate without a session deterministic_ecdsa_signatures: Deterministic ECDSA signatures static-user-module: STATIC_USER trusted-attr-module: TRUSTED_ATTRIBUTE managed-user-module: MANAGED_USER internal-user-module: INTERNAL_USER client-cert-module: CLIENT_CERT client-cert-demo: Test client certificate authentication passthrough-module: PASSTHROUGH social-provider-module: SOCIAL_PROVIDERS iwa-module: IWA iwa-create-user: Create a specific Kerberos user account iwa-keytab: Create a keytab file iwa-openidm-config: Configure IDM for IWA --- # Authentication and session modules An authentication module specifies how a user or client is authenticated. You configure authentication and session modules in your project's `conf/authentication.json` file. IDM evaluates authentication modules in the order in which they appear in that file, and uses the first "successful" authentication module it finds. Subsequent modules are not evaluated. In a production environment, you should remove any unused authentication modules from your `authentication.json` file. To authenticate a user or client, IDM validates the provided credentials against some resource. That resource can be either an IDM resource such as `managed/user` or `internal/user`, or it can be an external resource such as an LDAP server or social identity provider. You should prioritize the authentication modules that query IDM resources over those that query external resources. Prioritizing modules that query external resources can lead to authentication problems for internal users such as `openidm-admin`. You can also configure authentication modules in the admin UI. Select Configure > Authentication, and select the Session or Module tab. To change the order of authentication modules in the admin UI, simply drag the modules up or down so that they appear in the order in which they should be evaluated. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Modifying an authentication module in the admin UI might affect your current session. In this case, IDM prompts you with the following message:``` Your current session may be invalid. Click here to logout and re-authenticate. ```When you select the Click here link, IDM logs you out of any current session and returns you to the login screen. | IDM supports the following authentication and session modules: ## JWT_SESSION IDM supports one session module, the JSON Web Token (JWT) Session Module. When a client authenticates successfully, the JWT Session Module creates a JWT and sets it as a cookie on the response. On subsequent requests, the module checks for the presence of the JWT as a cookie on the request, validates the signature and decrypts it, and checks the expiration time of the JWT. JWT sessions are entirely stateless, that is, they are not persisted in the backend. All information pertaining to the session is encrypted in the JWT. When a request to IDM produces a JWT, that value replaces the previous one used to send that request. In this way the JWT is always updated to the latest copy. The idle timeout in the JWT is therefore continuously updated and active sessions are not abruptly killed mid-session. By default, the JWT cookie is deleted on logout. Deleting the cookie manually ends the session. You can modify what happens to the session after a browser restart by changing the value of the `sessionOnly` property. The default JWT Session Module configuration, in `conf/authentication.json`, is as follows: ```json "sessionModule" : { "name" : "JWT_SESSION", "properties" : { "maxTokenLifeMinutes" : 120, "tokenIdleTimeMinutes" : 30, "sessionOnly" : true, "isHttpOnly" : true, "enableDynamicRoles" : false } } ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * In a production environment, ensure that only secure cookies are used. To do so, add the following property to the session module configuration: ```json "isSecure" : true ``` * If your `authentication.json` file uses a non-default cookie name for `name.openidm.csrfFilter.authCookieName`, add the following property to the session module configuration: ```json "sessionCookieName": "customCookieName" ``` | For more information about this module, refer to the [Class JwtSessionModule JavaDoc](https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/jaspi/modules/session/jwt/JwtSessionModule.html). Attempting to access IDM without the appropriate headers or session cookie results in an HTTP 401 Unauthorized, or HTTP 403 Forbidden, depending on the situation. If you authenticate using a session cookie, you must include an additional header that indicates the origin of the request. The following example shows a successful authentication attempt and the return of a session cookie: ``` curl \ --dump-header /dev/stdout \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --cacert ca-cert.pem \ "https://localhost:8443/openidm/managed/user?_queryFilter=true&_fields=_id" HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Cache-Control: no-cache Set-Cookie: session-jwt=2l0zobpuk6st1b2m7gvhg5zas ...;Path=/ Expires: Thu, 01 Jan 1970 00:00:00 GMT Vary: Accept-Encoding, User-Agent Content-Length: 82 Server: Jetty(8.y.z-SNAPSHOT) ``` The following example uses the cookie returned in the previous response, and includes the `X-Requested-With` header to indicate the origin of the request. The value of the header can be any string, but should be informative for logging purposes. If you do not include the `X-Requested-With` header, IDM returns HTTP 403 Forbidden: ``` curl \ --dump-header /dev/stdout \ --header "Cookie: session-jwt=2l0zobpuk6st1b2m7gvhg5zas ..." \ --header "X-Requested-With: OpenIDM Plugin" \ --header "Accept-API-Version: resource=1.0" \ --cacert ca-cert.pem \ "https://localhost:8443/openidm/managed/user?_queryFilter=true&_fields=_id" Expires: Thu, 01 Jan 1970 00:00:00 GMT Content-Type: application/json; charset=UTF-8 Cache-Control: no-cache Vary: Accept-Encoding, User-Agent Content-Length: 82 Server: Jetty(8.y.z-SNAPSHOT) ``` The expiration date of the JWT cookie, January 1, 1970, corresponds to the start of UNIX time. Since that time is in the past, browsers will not store that cookie after the browser session is closed. Authentication requests are logged in the `authentication.audit.json` file. A successful authentication request is logged as follows: ```json { "_id": "389d15d3-bdd5-4521-ae3c-bf096d334405-915", "timestamp": "2019-08-02T11:53:31.110Z", "eventName": "SESSION", "transactionId": "389d15d3-bdd5-4521-ae3c-bf096d334405-912", "trackingIds": [ "5f9f4941-bcbd-4cbc-97f7-e763808e4310", "88973bcf-0d60-41b8-9922-73718ce76e11" ], "userId": "openidm-admin", "principal": [ "openidm-admin" ], "entries": [ { "moduleId": "JwtSession", "result": "SUCCESSFUL", "info": { "org.forgerock.authentication.principal": "openidm-admin" } } ], "result": "SUCCESSFUL", "provider": null, "method": "JwtSession" } ``` For information about querying this log, refer to [Query the Authentication Audit Log](../audit-guide/querying-audit-over-rest.html#querying-auth-log). ### Authenticate without a session Once a client has authenticated, the `JWT_SESSION` takes precedence over any other authentication modules, for subsequent requests. In some cases, you might want to force clients to re-authenticate for each request. This is the case, for example, if you authenticate using a [client certificate](#client-cert-module). To request one-time authentication without a session, use the `X-OpenIDM-NoSession` header in the authentication request. For example: ```http curl \ --dump-header /dev/stdout \ --header "X-OpenIDM-NoSession: true" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --cacert ca-cert.pem \ --header "Accept-API-Version: resource=1.0" \ "https://localhost:8443/openidm/managed/user?_queryFilter=true&_fields=_id" HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Cache-Control: no-cache Vary: Accept-Encoding, User-Agent Content-Length: 82 Server: Jetty(8.y.z-SNAPSHOT) ``` ### Deterministic ECDSA signatures By default, JWTs are signed with [deterministic Elliptic Curve Digital Signature Algorithm (ECDSA)](https://www.rfc-editor.org/rfc/rfc6979.html). In order to use this more secure signing method, [Bouncy Castle](https://www.bouncycastle.org), which is included in the default IDM installation, must be installed. If Bouncy Castle is unavailable, or the key is incompatible, IDM falls back to normal ECDSA. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you need to turn off the use of deterministic ECDSA, set the following property in your `conf/system.properties` file:```properties org.forgerock.secrets.preferDeterministicEcdsa=false ``` | ## STATIC_USER The `STATIC_USER` module provides an authentication mechanism that avoids database lookups by hard coding a static user. IDM includes a default `anonymous` static user, but you can create any static user for this module. The following sample REST call uses `STATIC_USER` authentication with the `anonymous` user in the self-registration process: ``` curl \ --header "X-OpenIDM-Password: anonymous" \ --header "X-OpenIDM-Username: anonymous" \ --header "Accept-API-Version: resource=1.0" \ --cacert ca-cert.pem \ --header "Content-Type: application/json" \ --request POST \ --data '{ "userName": "steve", "givenName": "Steve", "sn": "Carter", "telephoneNumber": "0828290289", "mail": "scarter@example.com", "password": "Passw0rd" }' \ "https://localhost:8443/openidm/managed/user/?_action=create" ``` | | | | - | ---------------------------------------------------------------------------- | | | This is not the same as an anonymous request that is issued without headers. | Authenticating with the `STATIC_USER` module avoids the performance cost of reading the database for self-registration, certain UI requests, and other actions that can be performed anonymously. Authenticating the anonymous user with the `STATIC_USER` module is identical to authenticating the anonymous user with the `INTERNAL_USER` module, except that the database is not accessed. So, `STATIC_USER` authentication provides an authentication mechanism for the anonymous user that avoids the database lookups incurred when using `INTERNAL_USER`. A sample `STATIC_USER` authentication configuration follows: ```json { "name" : "STATIC_USER", "enabled" : true, "properties" : { "queryOnResource" : "internal/user", "username" : "anonymous", "password" : "anonymous", "defaultUserRoles" : [ "internal/role/openidm-reg" ] } } ``` IDM also uses the `STATIC_USER` module to set the password and default roles of the `openidm-admin` internal user on startup. The following configuration in the `authentication.json` file sets up the `openidm-admin` user: ```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 } ``` Related topics: * [Change the administrator user password (`openidm-admin`)](authenticating-users.html#change-default-admin-pwd) * [Secure access to RCS](authorization-and-roles.html#secure-openicf-access) ## TRUSTED_ATTRIBUTE The `TRUSTED_ATTRIBUTE` authentication module lets you configure IDM to trust a specific `HttpServletRequest` attribute. To enable this module, add it to your `authentication.json` file as follows: ```json { "name" : "TRUSTED_ATTRIBUTE", "properties" : { "queryOnResource" : "managed/user", "propertyMapping" : { "authenticationId" : "userName", "userRoles" : "authzRoles" }, "defaultUserRoles" : [ ], "authenticationIdAttribute" : "X-ForgeRock-AuthenticationId", "augmentSecurityContext" : { "type" : "text/javascript", "file" : "auth/populateRolesFromRelationship.js" } }, "enabled" : true } ``` `TRUSTED_ATTRIBUTE` authentication queries the `managed/user` resource, and allows authentication when credentials match, based on the `username` and `authzRoles` assigned to that user, specifically the `X-ForgeRock-AuthenticationId` attribute. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To use the `TRUSTED_ATTRIBUTE` module with internal `authz` roles, you must modify the `isAJAXRequest` function in `bin/defaults/script/router-authz.js` to check for the `X-Special-Trusted-User` header:```javascript function isAJAXRequest() { var headers = context.http.headers; // one of these custom headers must be present for all HTTP-based requests, to prevent CSRF attacks // X-Requested-With is common from AJAX libraries such as jQuery if (typeof (headers["X-Requested-With"]) !== "undefined" || typeof (headers["x-requested-with"]) !== "undefined" || // Basic auth headers are acceptible for convenience from cURL commands; // We don't return the request header to prompt the browser to provide basic auth headers, // so it will only be present if someone explicitly provides them, as in a cURL request. typeof (headers["Authorization"]) !== "undefined" || typeof (headers["authorization"]) !== "undefined" || // The custom authn headers for OpenIDM typeof (headers["X-OpenIDM-Username"]) !== "undefined" || typeof (headers["x-openidm-username"]) !== "undefined" || typeof (headers["X-Special-Trusted-User"]) !== "undefined" || typeof (headers["x-special-trusted-user"]) !== "undefined") { if ((headers["X-Requested-With"] || "").toLowerCase().startsWith("shockwaveflash")) { // prevent CSRF from Flash return false; } return true; } return false; } ``` | For a sample implementation of a custom servlet filter and the Trusted Request Attribute Authentication Module, refer to [Authenticate using a trusted servlet filter](../samples-guide/trusted-servlet-filter.html). ## MANAGED_USER `MANAGED_USER` authentication queries the repository and allows authentication if the credentials match. Despite the module name, the query is not restricted to managed/user objects. The resource that is queried is configurable. The default configuration uses the `username` and `password` of a managed user to authenticate, as shown in the following sample configuration: ```json { "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 } ``` Use the `augmentSecurityContext` property to add custom properties to the security context of users who authenticate with this module. By default, this property adds a list of *protected properties* to the user's security context. These protected properties are defined in the managed object schema. The `isProtected` property is described in [Create and modify object types](../objects-guide/creating-modifying-managed-objects.html). ## INTERNAL_USER `INTERNAL_USER` authentication queries the `internal/user` objects in the repository and allows authentication if the credentials match. An example configuration that uses the `username` and `password` of the internal user to authenticate follows: ```json { "name" : "INTERNAL_USER", "enabled" : true, "properties" : { "queryId" : "credential-internaluser-query", "queryOnResource" : "internal/user", "propertyMapping" : { "authenticationId" : "username", "userCredential" : "password", "userRoles" : "authzRoles" }, "defaultUserRoles" : [ ] } } ``` ## CLIENT_CERT Client certificate authentication (also called *mutual SSL authentication*) occurs as part of the SSL or TLS handshake, which takes place before any data is transmitted in an SSL or TLS session. This authentication module is typically used when users have secure certificates that they install in their browsers for authentication and authorization. The client certificate module, `CLIENT_CERT`, authenticates by validating a client certificate, transmitted through an HTTP request. IDM compares the subject DN of the request certificate with the subject DN of the truststore. A sample `CLIENT_CERT` authentication configuration follows: ```json { "name" : "CLIENT_CERT", "properties" : { "augmentSecurityContext" : { "type" : "text/javascript", "globals" : { }, "file" : "auth/mapUserFromClientCert.js" }, "queryOnResource" : "managed/user", "defaultUserRoles" : [ "internal/role/openidm-authorized" ], "allowedAuthenticationIdPatterns" : [ ".*CN=localhost, O=ForgeRock.*" ] }, "enabled" : true } ``` When a user authenticates with a client certificate, they receive the roles listed in the `defaultUserRoles` property of the `CLIENT_CERT` module. Privileges are calculated dynamically per request when enabled in the session module. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Client certificate authentication is also used when the client is a password plugin, such as those described in [Password Plugins](../pwd-plugin-guide/preface.html). This process is similar to an administrative request to modify the passwords of regular users.For password plugin clients, you must include `internal/role/openidm-cert` in the `defaultUserRoles` array (in the authentication configuration *(tooltip: You can manage the authentication configuration over REST at the config/authentication endpoint, or directly in the conf/authentication.json file.)*). | ### Test client certificate authentication This procedure demonstrates client certificate authentication by generating a self-signed certificate, adding that certificate to the truststore, then authenticating with the certificate. At the end of this procedure, you will verify the certificate over port `8444` as defined in your project's `resolver/boot.properties` file: ``` openidm.auth.clientauthonlyports=8444 ``` The example assumes an existing managed user, bjensen, with email address `bjensen@example.com`. 1. Create a self-signed certificate for user bjensen as follows: ``` openssl req \ -x509 \ -newkey rsa:1024 \ -keyout /path/to/key.pem \ -out /path/to/cert.pem \ -days 3650 \ -nodes Generating a 1024 bit RSA private key ................. .................. writing new private key to 'key.pem' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) []: US State or Province Name (full name) []: Washington Locality Name (eg, city) []: Vancouver Organization Name (eg, company) []: Example.com Organizational Unit Name (eg, section) []: Common Name (eg, fully qualified host name) []: localhost Email Address []: bjensen@example.com ``` | | | | - | --------------------------------------------------------------------------------------------------------------- | | | The `Email Address` is used by the `mapUserFromClientCert.js` to map the user against an existing managed user. | 2. Import the client certificate into the IDM truststore: ``` keytool \ -importcert \ -keystore /path/to/openidm/security/truststore \ -storetype JKS \ -storepass changeit \ -file /path/to/cert.pem \ -trustcacerts \ -noprompt \ -alias client-cert-example Certificate was added to keystore ``` By default, users can authenticate only if their certificates have been issued by a Certificate Authority (CA) that is listed in the truststore. The default truststore includes several trusted root CA certificates, and any user certificate issued by those CAs will be trusted. Change the value of this property to restrict certificates to those issued to users in your domain, or use some other regular expression to limit who will be trusted. If you leave this property empty, no certificates will be trusted. 3. Edit your project's `conf/authentication.json` file. Add the `CLIENT_CERT` module, and add at least the email address from the certificate subject DN to the `allowedAuthenticationIdPatterns`: ```json { "name": "CLIENT_CERT", "properties": { "augmentSecurityContext": { "type": "text/javascript", "globals": {}, "file": "auth/mapUserFromClientCert.js" }, "queryOnResource": "managed/user", "defaultUserRoles": [ "internal/role/openidm-cert", "internal/role/openidm-authorized" ], "allowedAuthenticationIdPatterns": [ ".*EMAILADDRESS=bjensen@example.com.*" ] }, "enabled": true } ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `allowedAuthenticationIdPatterns` property is unique to this authentication module. This property contains a regular expression that defines which user distinguished names (DNs) are allowed to authenticate with a certificate. | 4. Send an HTTP request with your certificate file `cert.pem` to the secure port: ``` curl \ --insecure \ --cert-type PEM \ --key /path/to/key.pem \ --key-type PEM \ --cert /path/to/cert.pem \ --header "X-Requested-With: curl" \ --header "X-OpenIDM-NoSession: true" \ --request GET "https://localhost:8444/openidm/info/login" { "_id": "login", "authenticationId": "EMAILADDRESS=bjensen@example.com, CN=localhost, O=Example.com, L=Vancouver, ST=Washington, C=US", "authorization": { "userRolesProperty": "authzRoles", "component": "managed/user", "authLogin": false, "roles": [ "internal/role/openidm-cert", "internal/role/openidm-authorized" ], "ipAddress": "0:0:0:0:0:0:0:1", "id": "aba3e666-c0db-4669-8760-0eb21f310649", "moduleId": "CLIENT_CERT" } } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * Because we have used a self-signed certificate in this example, you must include the `--insecure` option. You should not include this option if you are using a CA cert. * You must use the `X-Requested-With` and `X-OpenIDM-NoSession` headers for HTTP-based requests that use the `CLIENT_CERT` authentication module. | ## PASSTHROUGH `PASSTHROUGH` authentication queries an external system, such as an LDAP server, and allows authentication if the credentials included in the REST request match those in the external system. The following excerpt of an `authentication.json` shows a pass-through authentication configuration for an LDAP system: ```json "authModules" : [ { "name" : "PASSTHROUGH", "enabled" : true, "properties" : { "augmentSecurityContext": { "type" : "text/javascript", "file" : "auth/populateAsManagedUser.js" }, "queryOnResource" : "system/ldap/account", "propertyMapping" : { "authenticationId" : "uid", "groupMembership" : "ldapGroups" }, "groupRoleMapping" : { "internal/role/openidm-admin" : ["cn=admins,ou=Groups,dc=example,dc=com"] }, "defaultUserRoles" : [ "internal/role/openidm-authorized" ] }, }, ... ] ``` For more information on authentication module properties, refer to [Authentication and session module configuration](appendix-auth-modules.html). Many of the documented [samples](../samples-guide/samples-provided.html) are configured for pass-through authentication. For example, the `sync-with-ldap*` samples use an external LDAP system for authentication. ## SOCIAL_PROVIDERS | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Social authentication is deprecated and will be removed in a future release of IDM. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html#deprecated-standalone-socialid-auth). | The `SOCIAL_PROVIDERS` module enables authentication through social identity providers that comply with OAuth 2.0 and OpenID Connect 1.0 standards. For information about configuring this module with social identity providers such as Google, LinkedIn, and Facebook, refer to [Social providers authentication module](../self-service-reference/cdm-social-providers.html). The `/path/to/openidm/audit/authentication.audit.json` log file shows the corresponding `SOCIAL_AUTH` module, used to handle authentication for each social identity provider. ## IWA | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The IWA module is deprecated and will be removed in a future release of IDM. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html#deprecated-IWA-auth). | The `IWA` module lets users authenticate using Integrated Windows Authentication (IWA) with Kerberos instead of a username and password. Windows, UNIX, and Linux systems support Kerberos v5 authentication, which can operate safely on an open, unprotected network. With Kerberos authentication, the user or client application obtains temporary credentials for a service from an *authorization server*, in the form of tickets and session keys. The *service server* handles its part of the Kerberos mutual authentication process. To enable Kerberos authentication, IDM requires a specific Kerberos user account in Active Directory, and a keytab file that maps the service principal to this user account. The client presents IDM with a Kerberos ticket. If IDM can validate the ticket, the client is granted an encrypted session key for the IDM service. That client can then access IDM without providing a username or password, for the duration of the session. The complete Kerberos authentication process is shown in the following diagram: Client Authentication to IDM Using a Kerberos Ticket ![kerberos-auth](_images/kerberos-auth.png) This section assumes that you have an active Kerberos server acting as a Key Distribution Center (KDC). If you are running Active Directory, that service includes a Kerberos KDC by default. ### Create a specific Kerberos user account To authenticate IDM to the Kerberos KDC you must create a specific user entry in Active Directory whose credentials will be used for this authentication. This Kerberos user account must not be used for anything else. The Kerberos user account is used to generate the Kerberos keytab. If you change the password of this Kerberos user after you have set up IWA, you must update the keytab accordingly. Create a new user in Active Directory as follows: 1. Select New > User and provide a login name for the user that reflects its purpose; for example, **openidm\@example.com**. 2. Enter a password for the user. Select the Password never expires checkbox, and leave all other options unselected. If the password of this user account expires, and is reset, you must update the keytab with the new password. It is therefore easier to create an account with a password that does not expire. 3. To create the user, click Finish. ### Create a keytab file A Kerberos keytab file (`krb5.keytab`) enables IDM to validate the Kerberos tickets that it receives from client browsers. You must create a Kerberos keytab file for the host on which IDM is running. This section describes the `ktpass` command, included in the Windows Server toolkit, to create the keytab file. Run the `ktpass` command on the Active Directory domain controller. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * The keytab file is case-sensitive, use the capitalization in this example. * You must disable UAC or run the `ktpass` command as a user with administrative privileges. | The following command creates a keytab file (named `openidm.HTTP.keytab`) for the IDM service located at `openidm.example.com`. ``` C:\Users\Administrator>ktpass ^ -princ HTTP/openidm.example.com@EXAMPLE.COM ^ -mapUser EXAMPLE\openidm ^ -mapOp set ^ -pass Passw0rd1 ^ -crypto ALL -pType KRB5_NT_PRINCIPAL ^ -kvno 0 ^ -out openidm.HTTP.keytab Targeting domain controller: host.example.com Using legacy password setting method Successfully mapped HTTP/openidm.example.com to openidm. Key created. Output keytab to openidm.HTTP.keytab: Keytab version: 0x502 keysize 79 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x1 (DES-CBC-CRC) keylength 8 (0x73a28fd307ad4f83) keysize 79 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x3 (DES-CBC-MD5) keylength 8 (0x73a28fd307ad4f83) keysize 87 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x17 (RC4-HMAC) keylength 16 (0xa87f3a337d73085c45f9416be5787d86) keysize 103 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x12 (AES256-SHA1) keylength 32 (0x6df9c282abe3be787553f23a3d1fcefc 6fc4a29c3165a38bae36a8493e866d60) keysize 87 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x11 (AES128-SHA1) keylength 16 (0xf616977f071542cd8ef3ff4e2ebcc09c) ``` The `ktpass` command takes the following options: * `-princ` specifies the service principal name in the format `service/host-name@realm` In this example (`HTTP/openidm.example.com@EXAMPLE.COM`), the client browser constructs an SPN based on the following: * The service name (HTTP). The service name for SPNEGO web authentication *must* be HTTP. * The FQDN of the host on which IDM runs (`openidm.example.com`). This example assumes that users will access IDM at the URL `https://openidm.example.com:8443`. * The Kerberos realm name (`EXAMPLE.COM`). The realm name must be uppercase. A Kerberos realm defines the area of authority of the Kerberos authentication server. * `-mapUser` specifies the name of the Kerberos user account to which the principal should be mapped (the account that you created in [Creating a Specific Kerberos User Account](#iwa-create-user)). The username must be specified in down-level logon name format (DOMAIN\UserName). In our example, the Kerberos user name is `EXAMPLE\openidm`. * `-mapOp` specifies how the Kerberos user account is linked. Use `set` to set the first user name to be linked. The default (`add`) adds the value of the specified local user name if a value already exists. * `-pass` specifies a password for the principal user name. Use `*` to prompt for a password. * `-crypto` specifies the cryptographic type of the keys that are generated in the keytab file. Use `ALL` to specify all crypto types. This procedure assumes a 128-bit cryptosystem, with a default RC4-HMAC-NT cryptography algorithm. You can use the `ktpass` command to view the crypto algorithm, as follows: ``` C:\Users\Administrator>ktpass -in .\openidm.HTTP.keytab Existing keytab: Keytab version: 0x502 keysize 79 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x1 (DES-CBC-CRC) keylength 8 (0x73a28fd307ad4f83) keysize 79 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x3 (DES-CBC-MD5) keylength 8 (0x73a28fd307ad4f83) keysize 87 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x17 (RC4-HMAC) keylength 16 (0xa87f3a337d73085c45f9416be5787d86) keysize 103 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x12 (AES256-SHA1) keylength 32 (0x6df9c282abe3be787553f23a3d1fcefc6 fc4a29c3165a38bae36a8493e866d60) keysize 87 HTTP/openidm.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x11 (AES128-SHA1) keylength 16 (0xf616977f071542cd8ef3ff4e2ebcc09c) ``` * `-ptype` Specifies the principal type. Use `KRB5_NT_PRINCIPAL`. * `-kvno` specifies the key version number. Set the key version number to 0. * `-out` specifies the name of the keytab file that will be generated, for example, `openidm.HTTP.keytab`. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The keys that are stored in the keytab file are similar to user passwords. You must protect the Kerberos keytab file in the same way that you would protect a file containing passwords. | For more information about the `ktpass` command, refer to the [ktpass reference](http://technet.microsoft.com/en-us/library/cc753771\(v=WS.10\).aspx) in the Windows server documentation. ### Configure IDM for IWA To configure the IWA authentication module, add the module to your project's `conf/authentication.json` file. This section assumes that the connection from IDM to the Active Directory Server is through an LDAP connector, and that the mapping from managed users to the users in Active Directory (in your project's `conf/sync.json` file) identifies the Active Directory target as `system/ad/account`. If you have named the target differently, modify the `"queryOnResource" : "system/ad/account"` property accordingly. Add the IWA authentication module towards the end of your `conf/authentication.json` file. For example: ```json "authModules" : [ ... { "name": "IWA", "properties": { "servicePrincipal": "HTTP/openidm.example.com@EXAMPLE.COM", "keytabFileName": "C:\\Users\\Administrator\\openidm\\security\\openidm.HTTP.keytab", "kerberosRealm": "EXAMPLE.COM", "kerberosServerName": "kdc.example.com", "queryOnResource": "system/ad/account", "maxTokenSize": 48000, "propertyMapping": { "authenticationId": "sAMAccountName", "groupMembership": "memberOf" }, "groupRoleMapping": { "internal/role/openidm-admin": [ ] }, "groupComparisonMethod": "ldap", "defaultUserRoles": [ "internal/role/openidm-authorized" ], "augmentSecurityContext": { "type": "text/javascript", "file": "auth/populateAsManagedUser.js" } }, "enabled": true }, ... ] ``` The IWA authentication module includes the following configurable properties: * `servicePrincipal` The Kerberos principal for authentication, in the following format: ``` HTTP/host.domain@DC-DOMAIN-NAME ``` host and domain correspond to the host and domain names of the IDM server. DC-DOMAIN-NAME is the domain name of the Windows Kerberos domain controller server. The DC-DOMAIN-NAME can differ from the domain name for the IDM server. * `keytabFileName` The full path to the keytab file for the Service Principal. On Windows systems, any backslash (`\`) characters in the path must be escaped, as shown in the previous example. * `kerberosRealm` The Kerberos Key Distribution Center realm. For the Windows Kerberos service, this is the domain controller server domain name. * `kerberosServerName` The fully qualified domain name of the Kerberos Key Distribution Center server, such as that of the domain controller server. * `queryOnResource` The IDM resource to check for the authenticating user; for example, `system/ad/account`. * `maxTokenSize` During the Kerberos authentication process, the Windows server builds a token to represent the user for authorization. This property sets the maximum size of the token, to prevent DoS attacks, if the SPENGO token in the request being made is amended with extra data. The default maximum token size is `48000` bytes. * `groupRoleMapping` Enables you to grant different roles to users who are authenticated through the `IWA` module. You can use the `IWA` module in conjunction with the `PASSTHROUGH` authentication module. In this case, a failure in the `IWA` module lets users revert to forms-based authentication. To add the `PASSTHROUGH` module, follow [PASSTHROUGH](#passthrough-module).