Securing OpenAM

This chapter identifies best practices for securing your OpenAM deployment.

Avoiding Obvious Defaults

OpenAM includes default settings to make it easier for you to evaluate the software. Avoid these default settings in production deployments:

When connecting to LDAP, bind with a specific administrative account rather than a root DN account, if possible.
Change the default iPlanetDirectoryPro cookie name both in OpenAM (com.iplanet.am.cookie.name) and in your policy agent profiles (com.sun.identity.agents.config.cookie.name).
When installing OpenAM, do not use /openam or /opensso as the deployment URI.
Create an administrator in the Top Level Realm with a different ID than the default amadmin.
Create specific administrator users to track better who makes configuration changes.
Remove the demo user account. If you configure the embedded OpenDJ directory server as a configuration and CTS store, a demo account with the published default password changeit is created during the installation process. It is created inactive, and upgrading an older installation deactivates it if it is still active and still carries that password, but you should remove it altogether using the OpenAM console under Realms > Top Level Realm > Identities.
Remove the WS-Security agent identities, unless you use WS-Security or the Security Token Service. The installation process creates wsc, wsp, SecurityTokenService and agentAuth in the Top Level Realm, each with a password that is published in the installer source — wsc, wsp, SecurityTokenService and changeit respectively. They are created inactive, and upgrading an older installation deactivates any of them that is still active and still carries its default password. Remove them under Realms > Top Level Realm > Applications > Agents, or, if you do need them, give each a password of your own before activating it.
Be aware that the anonymous user of the Top Level Realm can no longer authenticate with a password. Earlier versions shipped it with the password anonymous, stored as a literal hash in the installer source and therefore identical on every installation, which made it a valid login on any deployment. It now holds no password at all, and OpenAM refuses to authenticate it with one even where an installation still stores the old value, so no upgrade action is needed. The Anonymous authentication module is unaffected: it grants a session on the strength of the user name, not a password. If you had given anonymous a password of your own and used it as an ordinary account, create a separate account for that purpose.
Set the list of Valid goto URL Resources. OpenAM redirects the user to the URL specified in the goto and gotoOnFail query string parameters supplied to the authentication interface in the login URL.

To protect against phishing attacks through open redirect, you can specify a list of valid URL resources against which OpenAM validates these URLs. OpenAM only redirects a user if the goto and gotoOnFail URL matches any of the resources specified in this setting.

If no setting is present, OpenAM accepts only goto and gotoOnFail URLs that point back at the OpenAM server itself: a relative URL always, and an absolute one when it names one of the origins the server answers on - the origin of the incoming request, the URL OpenAM was installed under, or a base URL pinned for the realm through the Base URL Source service with the Fixed value or Extension class provider. The header based providers are not used, since the headers they read are set by the caller, and an Extension class naming one of them is read the same way. Redirecting to another host therefore requires this list to be populated. Earlier versions treated an absent setting as permission to redirect anywhere, which made an unconfigured realm usable as an open redirect. To restore that behaviour, set the advanced server property org.openidentityplatform.openam.auth.goto.allowAnyUrlWithoutWhitelist to true - which brings back the whole of it, protocol relative and user information URLs included, so treat it as a way to keep an upgrade moving rather than a setting to leave in place. Populating this list is the better option, and it takes precedence over the property either way, as does a list OpenAM could not read: where the configuration store cannot be reached, the goto URL is held to the same rule as an unconfigured realm rather than accepted outright. The same list and the same property also decide the TARGET of the SAML 1.x artifact and POST profiles and the wreply of a WS-Federation sign-in request as a relying party, judged against the realm the session is created in; there a base URL pinned through the Base URL Source service is not counted as an origin of the server, so a proxied deployment either relies on the URL OpenAM was installed under or populates the list.

The XUI holds the goto of its login and logout pages, and the gotoOnFail of its login page, to the same list. Earlier versions of the XUI sent the browser to the goto of the address bar after login and to its gotoOnFail after a failed login, whatever OpenAM had made of them, and to the goto of a #logout/ link without asking OpenAM at all. After a failed login the XUI now follows the failure URL OpenAM answers with - the gotoOnFail when the list allows it, otherwise the failure URL configured for the login, if there is one. A logout goto can only be checked against the list while the session is still active; without one, the XUI follows only a relative URL or one on the origin it was loaded from.

To set the Valid goto URL Resources, use the OpenAM console, and navigate to Realms > Realm Name > Services. Click Add a Service, select Validation Service, and add one or more valid goto URLs, and then click Create.

When setting valid goto URLs, you can use the "" wildcard, where "" matches all characters except "?". For more specific patterns, use resource names with wildcards as described in the procedure, "Configuring Valid goto URL Resources".
Disable module based authentication for all OpenAM realms. Module based authentication lets users authenticate using the module=module-name login parameter. To disable module based authentication for a realm, select the realm in the OpenAM console, then select Authentication > Settings > Security and clear the Module Based Authentication check box.

Preparing to Follow the Examples in This Documentation

Procedures throughout this documentation set authenticate as the demonstration user demo with the password changeit, and a few of them name an authentication module directly in a login URL, as module=module-name. Both are settings a new installation no longer accepts, for the reasons given above. Before following such a procedure on a new installation, prepare the realm you are working in:

Activate the demo account and give it a password, under Realms > Top Level Realm > Identities > demo, and substitute that password wherever an example shows changeit. An account of your own does just as well; the examples name demo only because it used to be there.
Where an example logs in with module=module-name, either enable Module Based Authentication for that realm, under Realms > Realm Name > Authentication > Settings > Security, or authenticate against a chain that contains the module and name it with service=chain-name instead.

Delete the account, and switch module based authentication off again, once you are finished. Neither belongs in a deployment that is being used for anything real.

Protecting Network Access

Anytime users interact with a web service, there are risks. With OpenAM, you can reduce those risks by limiting what is exposed through the firewall using the following strategy:

Use a reverse proxy in front of OpenAM to allow access only to the necessary URLs. A reverse proxy exposes only those endpoints needed for an application. For example, if you need to expose the OAuth2/OpenID Connect endpoints and REST interface, then you should implement a reverse proxy.

The following figure shows the recommended architecture with a reverse proxy.

Leave ssoadm.jsp disabled in production. (Advanced property: ssoadm.disabled=true).
If possible in your deployment, control access to OpenAM console by network address, such that administrators can only connect from well-known systems and networks.
Restrict access to URIs that you do not use, and prevent internal endpoints, such as /sessionservice from being reachable over the Internet.

For a full list of endpoints, see "Service Endpoints" in the Reference.

Securing OpenAM Administration

Create realms for your organization(s) and separate administrative users from end users. For instructions, see "Configuring Realms".

To direct relevant users to the correct realms, you can then either:
- Use the realm=realm-name query string parameter.
- Create fully qualified domain name DNS aliases for the realms.
When customizing config/auth/default*/Login.jsp, make sure that you do not introduce any security vulnerabilities, such as cross-site scripting due to unvalidated input.
Create a policy agent profile for each policy agent. See "Configuring Policy Agent Profiles" for instructions.

Securing Communications

Keep communications secure by using encryption, properly configured cookies, and request and response signatures:

Protect network traffic by using HTTPS and LDAPS where possible.
When using HTTPS, use secure cookies, which are transmitted only over secured connections.

To configure OpenAM server to use secure cookies, in the OpenAM console, navigate to Configure > Server Defaults > Security. On the Cookie tab, select Secure Cookie, and then click Save Changes.

HttpOnly cookies are meant to be transmitted only over HTTP and HTTPS, and not through non-HTTP methods, such as JavaScript functions.

You can configure the OpenAM server to use HttpOnly cookies by navigating to Configure > Server Defaults > Advanced, and setting the com.sun.identity.cookie.httponly property’s value to true. Save your changes. Both the classic UI and the XUI support HttpOnly session cookies: when HttpOnly is enabled, the XUI relies on the automatically sent cookie instead of reading the token from JavaScript, and the /json/authenticate response delivers the token only through the Set-Cookie header rather than echoing tokenId in the response body. To keep returning tokenId in the body as well (for example, for non-browser or raw-REST integrations), set org.openidentityplatform.openam.httponly.allowTokenInBody to true. Note that doing so re-exposes the token to scripts on the OpenAM origin, so leave it at its default of false unless an integration requires it. For both properties, see com.sun.identity.cookie.httponly and org.openidentityplatform.openam.httponly.allowTokenInBody in "Configuration Reference" in the Reference.

Both properties are read once when the server starts, so you must restart the OpenAM server for a change to either of them to take effect.

com.sun.identity.cookie.httponly defaults to false to preserve the behaviour of existing integrations that read the session cookie, or the tokenId from the authentication response body, from script. Enabling HttpOnly is recommended for browser-facing deployments: an HttpOnly session cookie prevents a cross-site scripting flaw on the OpenAM origin from reading a replayable session token.

One known limitation applies: the OpenID Connect session management OP iframe (/oauth2/connect/checkSession) computes the browser state by reading the session cookie from JavaScript, so it cannot observe the session while HttpOnly is enabled.

To reduce cross-site request forgery (CSRF) exposure, OpenAM also sets a SameSite attribute on its cookies. A standard installation ships with org.openidentityplatform.openam.cookie.samesite=Lax. You can change this to Strict or None (the latter requires secure cookies) under Configure > Server Defaults > Security > Cookie.
Where possible, use subdomain cookies, and control subdomains in a specific DNS master.
Use cookie hijacking protection with restricted tokens, where each policy agent uses different SSO tokens for the same user. See "To Protect Against Cookie Hijacking" for instructions.
Use your own key, not the test key provided with OpenAM, to sign:
- SAML 2.0 authentication requests, authentication responses, and single logout requests
- XUI authentication IDs
See "To Change OpenAM Default test Signing Key " for instructions.
When using SAML v2.0, if the other entities in your circle of trust can handle encryption, then use encryption in addition to signing requests and responses.

Administering the amadmin Account

The built-in amadmin account cannot be disabled, deleted, or renamed, since it is hard-coded in the source code of several files.

If you want a user to have administration rights in OpenAM other than amadmin, delegate realm administration privileges to the new user. For more information about delegating realm administration privileges, see "Delegating Realm Administration Privileges".

Changing the amadmin User’s Password

In this section you will find procedures to change the password of the top-level administrator amadmin, when:

OpenAM is configured using an external configuration store.

See "To Change the amadmin User’s Password: External Configuration Store".
OpenAM is configured using the embedded OpenDJ instance as the configuration store. It may be configured with an external data store, or with the embedded OpenDJ instance as a data store.

See "To Change the amadmin User’s Password: Embedded Configuration Store".

To Change the amadmin User’s Password: External Configuration Store

If OpenAM is configured to use an external configuration store, perform the following steps to change the amadmin user’s password:

Log in to the OpenAM console as the administrator, amadmin.
Navigate to Realms > Top Level Realm > Subjects, and then click amAdmin.
On the Edit User page, select Edit next to Password.
On the Change Password page, enter the new password in the New Password field.
Click OK to save your changes.

If your deployment has multiple OpenAM servers, the new password replicates across all servers.

To Change the amadmin User’s Password: Embedded Configuration Store

If OpenAM is configured to use the embedded OpenDJ instance for the configuration store, you must change the passwords of the following two users in the embedded OpenDJ accounts to match the new amadmin password: You must change these two passwords in the embedded OpenDJ instance regardless of whether you use an external or embedded data store.

The cn=Directory Manager user, created during installation.
The global administrator, created in OpenDJ by OpenAM after a second OpenAM server has been added to the deployment.

Some functionality might not work if the OpenDJ directory manager, OpenAM administrator amadmin, and OpenDJ global administrator passwords are not identical. For example, adding new servers to the deployment.

To change the OpenAM amadmin, OpenDJ directory manager, and OpenDJ global administrator passwords and the required bindings, perform the following steps:

Back up your deployment as described in "Backing Up and Restoring OpenAM Configurations".
Log in to the OpenAM console as the administrator, amadmin.
Navigate to Realms > Top Level Realm > Subjects, and then click amAdmin.
On the Edit User page, select Edit next to Password.
On the Change Password page, enter the new password in the New Password field.
Click OK to save your changes.

If your deployment has multiple OpenAM servers, the new password replicates across all servers.
OpenAM binds to the embedded OpenDJ server using the cn=Directory Manager account. Change the cn=Directory Manager account’s bind password in the OpenAM configuration as follows:
1. Change the password for the configuration store binding:
  1. Navigate to Deployment > Servers > Server Name > Directory Configuration.
  2. Enter the new bind password, which is the new amadmin password, and save your changes.
    
    Make this change for each of your OpenAM servers.
2. (Optional) If you use the embedded OpenDJ instance as a data store, change the following bind passwords:
  1. Navigate to Realms > Realm Name > Data Stores > embedded:
    
    Enter the new bind password, which is the new amadmin password, and save your changes.
    
    Make this change in every OpenAM realm that uses the embedded OpenDJ as a data store.
  2. Navigate to Realms > Realm Name > Services > Policy Configuration:
    
    Enter the new bind password, which is the new amadmin password, and save your changes.
    
    Make this change in every OpenAM realm that uses the embedded OpenDJ as a data store.
  3. Navigate to Realms > Realm Name > Authentication > Modules, and select LDAP:
    
    Enter the new bind password, which is the new amadmin password, and save your changes.
    
    Make this change in every OpenAM realm that uses the embedded OpenDJ as a data store.
To change the cn=Directory Manager and the global administrator passwords in the embedded OpenDJ, see Resetting Administrator Passwords in the OpenDJ Administration Guide.