Authentication for IBM Storage Scale native REST API

When the IBM Storage Scale native REST API feature is deployed, authentication is enabled by default.

Authentication

The following authentication methods are supported for IBM Storage Scale native REST API:

Pluggable authentication modules (PAM)
Lightweight directory access protocol (LDAP)
OpenID connect (OIDC)
Active directory (AD) (through LDAP queries)
Certificate-based authentication

Note: After the authentication_type and its associated configuration are changed, restart the scaleadmd service for the new authentication type to take effect.

PAM

PAM authentication is supported by using the pam_unix module. It is the default authentication method for IBM Storage Scale native REST API. The pam_unix module validates a username and password against the system password database (/etc/passwd and /etc/shadow). The user who issues commands through the scalectl or the REST API must exist on the nodes where the commands are issued. IBM Storage Scale does not create these users. Cluster administrators must create these users, and ensure that these usernames do not overlap across cluster nodes.

When you use the scalectl command locally on a node, the administration daemon gets the peer client information from the unix domain socket (UDS). It uses the UID of the client to find the username for authorization. Because the user is already logged in locally, no additional authentication is done at this stage. The client username is then used for authorization as defined in the RBAC rules.

When you use the scalectl command with the --url flag or through third-party clients such as curl, authentication is sent through the HTTP header basic authentication scheme. The scalectl command requires a .netrc file in the home directory of the user profile. Use the NETRC environmental variable to specify a different path. scalectl does not attempt to resolve IP addresses or hostnames that are defined in the .netrc file. The IP address, hostname or fully qualified domain name (FQDN) must match the value that is provided in the --url flag. To match any machine, use the default keyword in the .netrc file. The same .netrc file can be used with curl by using the -n or --netrc flags. This file generates the same basic authentication header.

A sample .netrc file can include the following entries:

To match a specific host defined by the --url flag, use one or more machine entries:
```
machine <host> login <user> password <password>
```
To match any host defined by the --url flag, use a default entry. Include only one default entry, and place it after all machine entries:
```
default login <user> password <password>
```

The basic authorization scheme is used to pass the encoded username and password to the PAM for validation. This scheme is base64-encoded but not encrypted. However, HTTPS is used to connect to the administration daemon. Therefore, the username and password are encrypted in transit. The username and password are never cached or stored locally.

OIDC

OIDC authentication uses your organization identity provider to authenticate with IBM Storage Scale native REST API. Modify the administration daemon configuration to switch the authentication type to oidc-userinfo by using scalectl or REST APIs. After you modify the configuration, the subconfiguration that is defined under rest_server.oidc is used. Depending on your environment, the following options are supported:

rest_server.oidc.callback_url
rest_server.oidc.authorization_url
rest_server.oidc.token_url
rest_server.oidc.userinfo_url
rest_server.oidc.discovery_url
rest_server.oidc.client_id
rest_server.oidc.client_secret
rest_server.oidc.scope

Provide the callback_url in the subconfiguration and to your identity provider. If your identity provider supports the discovery_url, use this option instead of providing individual URLs for authorization_url, token_url, and userinfo_url. A specific URL provided for authorization_url, token_url, or userinfo_url takes precedence over any URL obtained through the discovery_url endpoint. The OAUTH_CLIENT_SECRET environment variable takes precedence over the client_secret configuration option. By default, openid is always included in the scopes. If required, add additional scopes, including email and profile.

Note: Restart scaleadmd for the changes to take effect.

To generate an OIDC token from your identity provider, complete the following steps:

Open a browser and go to the following URL, replacing <FQDN> with your organization’s fully qualified domain name (FQDN):
```
https://<FQDN>:46443/login
```
Enter your credentials to log in.
After successful authentication, the token is displayed in the browser in the following format:
```
{ "token": "<your_token>" }
```

For future requests, use the --bearer option with the scalectl command. If this option is set, scalectl requires the token to be specified in the OIDC_TOKEN environment variable.

The authorization bearer header scheme is used to pass the token for validation. The connection to scaleadmd uses HTTPS, ensuring that the token is encrypted in transit.

When scaleadmd authenticates a request, it forwards the token to the identity provider for validation. To reduce network traffic, validation results are cached for 10 seconds. If a token is revoked or expires, it might allow additional requests for up to 10 seconds due to caching.

LDAP

Similar to the PAM authentication, LDAP requires the .netrc file to contain the username and password that can be validated by the LDAP server. Modify the administration daemon configuration to switch the authentication type to ldap by using scalectl or REST API.

After you modify the configuration, the subconfiguration that is defined under rest_server.ldap is used. Depending on your environment, the following options are supported:

rest_server.ldap.url
rest_server.ldap.basedn
rest_server.ldap.filter
rest_server.ldap.binddn
rest_server.ldap.bind_password

The filter option must return a single result. If multiple results are returned, an error occurs. A bind is attempted by using the provided binddn and bind_password. If they are not set, an unauthenticated bind is used. The filter option replaces the %s placeholder with the username to be authenticated. The DN and password from the returned result are used to authenticate another bind request. If the bind is successful, authentication is completed and authorization proceeds with the provided username.

You can comment out or remove any configuration options that are not in use.

Note: Restart scaleadmd for the changes to take effect.

AD (through LDAP queries)

If your environment requires AD, enable the AD authentication through the LDAP configuration. LDAP can query AD servers, allowing the same LDAP configuration to be used for AD authentication.

Similar to the PAM and LDAP authentication, AD authentication requires the .netrc file to contain the username and password for validation by the AD server. Modify the administration daemon configuration to switch the authentication type to ldap by using the scalectl command or REST API. After you modify the configuration, the subconfiguration that is defined under rest_server.ldap is used. Depending on your environment, the following options are supported:

rest_server.ldap.url = "ldap://test1.xxx.stgxxx.ibm.com"
rest_server.ldap.basedn = "cn=users,dc=storage3test,dc=tuc,dc=stglabs,dc=ibm,dc=com"
rest_server.ldap.filter = "(sAMAccountName=%s)"
rest_server.ldap.binddn = "ADuser1@test1.xxx.stgxxx.ibm.com"
rest_server.ldap.bind_password = "&lt;password>"

Note: Restart scaleadmd for the changes to take effect.

Certificate-based authentication

Certificate-based authentication allows the use of certificates in the IBM Storage Scale native REST API. Modify the administration daemon configuration to switch the authentication type to cert by using scalectl or REST APIs.

After you modify the configuration, the subconfiguration that is defined under rest_server.cert is used. Depending on your environment, the following options are supported:

rest_server.cert.cachain
rest_server.cert.allowed_cns
rest_server.cert.allowed_cns_regex

cachain: Specifies the certificate authority (CA) certificate that signs the client certificates. If this field is not specified, the cluster node identity cachain is used.
allowed_cns: Specifies a list of common names (CNs) that are allowed. The CN from the authenticating certificate must exactly match one of the CNs in this list.
allowed_cns_regex: Uses a regular expression to match the CN of the authenticating certificate. For example, "local….$" matches localhost but not localhost1.
allowed_cns takes precedence over allowed_cns_regex. If neither is set, then it allows any CN if the certificate was signed by the cachain.

Note: If allowed_cns and allowed_cns_regex are both set, allowed_cns takes precedence. If both the allowed_cns and allowed_cns_regex are not set, any CN is allowed if the certificate was signed by the cachain.

After certificate-based authentication is enabled, use the --cert and --key flags with scalectl to issue requests to the administration daemon. The CN from the authenticated certificate is extracted and used as the username for authorization.