Authentication#

The majority of ICE ClusterWare™ API endpoints require that an authentication token is included in the request. This authentication token will usually come from a call to the login or token refresh endpoints. There are several authentication options for logging in:

  • Username / Password authentication. This leverages the operating system's login credentials.

  • SSH key authentication. This uses a public / private key pair. The private keys must be set inside the ClusterWare software.

  • Local-socket authentication service. This only works if a user is logged in to the head node where the request is made.

When the login is successful, two JSON Web Tokens (JWTs; see https://jwt.io/) will be returned: an access token and a refresh token. The refresh token can be presented to the token-refresh endpoint to make a new access token.

Note

The ClusterWare command-line tools use the access token when possible and will automatically use the refresh token when the access token has expired. Admins writing their own tools will have to detect errors due to token expiration and manually initiate a refresh.

While there are ways to unpack and interpret the data inside a JWT, the tokens can be considered opaque. A client simply receives a JWT upon login, and then sends that same JWT inside an authorization header on future requests:

Header:  “Authorization:  Bearer  eyJhbGciOiJIUzI1Ni…”

The access token has an embedded expiration time (which is also sent by the ClusterWare platform during the login process) and after that time, the token will be rejected by the head node. The refresh token has its own expiration time, usually much longer than the access token. So the expectation is that when the access token expires, the refresh token will still be valid and can be used to make a new access token.

Note

While the refresh token is ONLY usable for making a new access token, it cannot be used to interact with the other endpoints.

In a multi-head cluster, every head node may be configured to use different underlying “secrets” that are used when making new tokens. Thus, after authenticating to one head node, the tokens that are returned may not be usable on other head nodes. In the rare case that a client needs to interact with multiple head nodes, it should login to each one separately and ensure that future requests use the correct token with each corresponding head node.

Where authentication asserts that “this user is who they say they are”, the ClusterWare platform uses role-based access control (RBAC) to limit what specific actions a given user can take. For more information on ClusterWare’s RBAC roles, see Role-Based Access Controls and Role-Based Access Control System.

Note

As with other token-based authentication systems, if anyone intercepts or acquires a copy of a token, they can fully impersonate the user who created it. Care must be taken to protect the tokens from other users. Consider using OS or file-system based access control mechanisms.

Username/Password Authentication#

The traditional username/password process is provided through a PAM connector. When a login request is made, the system is queried to see if the given username and password are valid. If they are, the ClusterWare platform will make a new token and return it to the caller.

The data is sent as a JSON object with "user" and "pass" keys:

curl -X POST https://head1.cluster.local/api/v1/login --data '{"user":"admin1", \
    "pass":"password"}'

Note that these example curl commands are interacting with an HTTP endpoint, but they are also available using HTTPS. Further, the examples may show passwords on the command line, but putting a password on the command line is not recommended as it may be visible to other users via ps or similar commands.

The returned value will include the access and refresh tokens, as well as expiration values for both:

{"success": true, "data": {"user": "admin1", "token": {"access_token": \
    "eyJhbGciOiJIUzI1Ni…", "expires_in": 1200, "refresh_token": \
    "eyJhbGciOiJIUzI1Ni…", "refresh_expires_in": 2592000}}}

The expiration times are in seconds from when the server issued the token. For long-running actions or scripts, admins may want to err on the side of caution and refresh prior to the actual expiration of the access token.

Note

While the head nodes synchronize data amongst themselves, the underlying operating systems do not synchronize unless configured to do so via some other mechanism. The head nodes could have their /etc/passwd and /etc/shadow files synchronized through scp or sftp, or through an external directory system (LDAP, NIS), but that is outside the scope of this document.

Token Refresh#

The access token can be used in subsequent requests up until the expiration time. Once it has expired, the refresh token can be used to acquire a new access token through the token-refresh endpoint:

curl -X GET https://head1.cluster.local/api/v1/newtoken -H "Authorization: \
    Bearer eyJhbGciOiJIUzI1Ni…"

Again, note that this should be the refresh token that is sent to this endpoint – sending an access token will result in a failure.

Upon success, a new set of tokens will be returned:

{"success": true, "data": {"authorized_by": "admin1", "userid": "admin1", "uid": \
    "735367a122664db8ae8ba3ec113f1643", "token": {"access_token": \
    "eyJhbGciOiJIUzI1Ni…", "expires_in": 1200, "refresh_token": \
    "eyJhbGciOiJIUzI1Ni…", "refresh_expires_in": 2592000}}}

If the authentication fails, the "success" field will be false and a "reason" field will contain more information.

Note

The default access token duration is 20 minutes; the default refresh token duration is 30 days.

Alternate Authentication Methods#

There are two other authentication methods that can be used during login – a one-time password (OTP) sent to a local socket, and SSH-key authentication. For more information, please contact Penguin Solutions.

Since head nodes are assumed to be “locked down” and protected from end-user access, when a client is running on the head node, they can send an OTP to a known Unix socket and then re-send that OTP during the login process. The same POST /login endpoint is used, but with “user” and “secret” keys. If successful, the ClusterWare platform will return a set of access and refresh tokens.

For information on the SSH-key login process, please contact Penguin Solutions.