User Authentication

Authentication is based on authentication realms associated with users. A user is uniquely identified by a user name, and has a set of attributes. These attributes include:

  • Authentication Realm — Authentication realm in which user is defined.

  • User Name — Unique identifier for this user.

  • Password — Credential for this user.

  • Roles — One or more roles granting privileges to this user.

  • Password Expiration — The duration in days that the password is valid.

  • Trusted Hosts Only — Allow access only from trusted hosts, or from any host (defined by authentication realm).

  • Password Required — Define whether a password is always required, or only from untrusted hosts (defined by authentication realm).

  • Automatic Secure Communication Authentication — Define whether a user is automatically authenticated without a password when connecting over a secure (e.g. TLS) communication channel (defined by authentication realm).

These attributes are defined using administrative commands, or loading and activating configuration files.

See epadmin add user for details on how a user is defined.

Authentication verifies that a given user is valid and that the presented password matches the password defined for the user. The presented password is validated using the mechanism defined by the authentication realm. Once authentication succeeds, all work done in the context of the current administration command will be done in an authenticated session for that user. Any access to secured resources during that session will require that the user was granted a role which has access privileges for the resource. User definitions may be updated, for example to change the password, or the set of granted roles. See epadmin update user for details on how to update an existing user definition.

User can discover which realm the Admin web service is configured from the WWW-Authenticate header of 401 Unauthorized response. The Admin UI can discover this by making changes in the security module as follows:

• Local-auth-realm: 401, WWW-Authenticate Basic realm=application 
• LADP realm:       401, WWW-Authenticate Basic realm=application 
• Kerberos realm:   401, WWW-Authenticate Negotiate            
• OIDC realm:       401, WWW-Authenticate Bearer realm=application  

Web Services

All access through a web service endpoint must be authenticated using HTTP basic access authentication. This requires the HTTP user agent, for example a web browser, to provide a user name and password. The user name and password is authenticated by the authentication realm associated with the web service. By default, web service authentication uses the node administration realm. The authentication realm to use can be changed per web service using the WebServiceBinding configuration object (see WebServiceBinding) in a node deploy configuration. It is also possible to disable authentication for a web service using the WebServiceBinding configuration object.


In general, disabling authentication is not recommended. Only disable authentication after a full evaluation of the security implications.

As shown in Figure 1, “Web services authentication” web services authentication consists of these steps:

  1. a username and password are sent from the client user agent.

  2. the username and password are authenticated using the web service authentication realm.

Web services authentication

Web services authentication

Web services support the local (see Configuration of Local Authentication Realm) and LDAP (see Configuration of LDAP Authentication Realm) authentication realms with no support for trusted hosts. This implies that a valid username and password must always be provided when accessing a web service endpoint. The default user created when a node is installed (see Default Security) is not typically useful for accessing web service endpoints because the password is not known. Additional users should be added as required to support access to web service endpoints, for example, if a local authentication realm is being used, users should be added to the realm as described in epadmin add user.

There may be additional authentication required by the endpoint implementation. See Supported Web Services for details.

Secure Shell (SSH)

The epadmin command-line tool provides administrative access to nodes running on both local and remote hosts. Some commands sent to nodes running on remote hosts are executed using Secure Shell (SSH) connections. SSH is a tool which provides authentication and confidentiality for network connections to remote hosts.

SSH is used when there is not a node coordinator running on the remote node. Specifically these epadmin commands use SSH when the global hostname parameter specifies a non-local host.

  • install node

  • start node --installpath=<path>

  • remove node --installpath=<path>

  • getadminport node --installpath=<path>

SSH requires configuration of authentication keys for the operating system user who executes the remote command. Authentication keys for SSH are generated using the ssh-keygen command-line tool. See the ssh-keygen manual page (run man ssh-keygen from a terminal) for further information on how to generate authentication keys, and where the keys must be stored for SSH to make use of them.