documents > User's Manual > SASL over TLS Authentication

SASL over TLS Authentication

English | Japanese

This document describes the settings required for SASL over TLS authentication in Gfarm.

There are two types of SASL authentication in Gfarm.

sasl: Not only the authentication process, but also metadata access and file access are performed over a TLS-encrypted communication.
sasl_auth: Only the SASL authentication phase is encrypted with TLS, and subsequent metadata access and file access are communicated in plain text.

TLS configuiration

Since SASL authentication uses TLS-encrypted communication, the settings described in "Common settings for tls_sharedsecret authentication, tls_client_certificate authentication, sasl authentication and sasl_auth authentication" in "TLS Authentication" must be configured in advance.

Settings to server

Place the following configuration file named gfarm.conf in the Cyrus SASL configuration directory ($(pkg-config --variable=libdir libsasl2)/sasl2).
In this document, this file will be referred to as the "Cyrus SASL server configuration file".

mech_list: the SASL authentication mechanisms to be used
...If other mechanism-specific settings are required, describe them.

Multiple mechanisms can be described in mech_list, separated by spaces as follows.

For example,

mech_list: PLAIN XOAUTH2

If this file is not present, all SASL mechanisms installed on the system are candidates for use.
However, this can lead to problems, so only specify the mechanisms that you actually use.

Please refer to the Cyrus SASL documentation for configuration settings related to all mechanisms except XOAUTH2. For the XOAUTH2 mechanism, please refer to the following.

Configuration for XOAUTH2 mechanism

To use the XOAUTH2 mechanism, install the cyrus-sasl-xoauth2-idp package and place the following settings in the Cyrus SASL server configuration file under the name gfarm.conf.

mech_list: XOAUTH2
xoauth2_scope: scope required in JWT, used for server-side validation
xoauth2_aud: audience required in JWT, used for server-side validation
xoauth2_user_claim: key name of claim to be used as user ID in JWT
xoauth2_issuers: a list of trusted issures of JWT

The specific configuration depends on the OAuth IdP, but here is an example.

mech_list: XOAUTH2
xoauth2_scope: hpci
xoauth2_aud: hpci
xoauth2_user_claim: hpci.id
xoauth2_issuers: https://keycloak.example.com/auth/realms/hpci https://keycloak.example.org/auth/realms/hpci

When xoauth2_issuers is not specified, any issuer is trusted. We highly recommend to specify xoauth2_issuers to accept JWTs issued by only trusted issuers.

The server side accesses the IdP, but if you need to use a web proxy server for this, add the following setting:

proxy: http://PROXY-SERVER-NAME:PROXY-PORT-NUMBER/

Modify "PROXY-SERVER-NAME" and "PROXY-PORT-NUMBER" as appropriate.

On Ubuntu, authentication to gfsd may fail due to the error "unable to open Berkeley db /etc/sasldb2: Permission denied". This is a workaround for this error.

% sudo chown _gfarmfs /etc/sasldb2

Gfarm configuration

Add the following settings to gfmd.conf for gfmd, and gfarm2.conf which is read by gfsd

auth enable sasl *

auth enable sasl_auth *

Also, please add the following settings to limit the mechanisms used.

sasl_mechanisms "PLAIN XOAUTH2"

For security purposes, specify only the mechanism actually used.
For other settings, follow the Cyrus SASL documentation.

When the user name in SASL (SASL-username) and Gfarm (Gfarm-username) is different, register SASL user name as follows.

% gfuser -A Gfarm-username SASL SASL-username

Client-side configuration

Set the file specified by the GFARM_CONFIG_FILE environment variable, or, if the environment variable is not set, in .gfarm2rc in your home directory, as follows, depending on the SASL mechanism you are using. Please modify "USER-NAME" and "PASSWORD" as appropriate.

For ANONYMOUS mechanism

sasl_mechanisms "ANONYMOUS"
sasl_user "dummy-user-name"

Since the anonymous mechanism configuration does not contain any user-specific information, it can also be set in gfarm2.conf.

For PLAIN mechanism

sasl_mechanisms "PLAIN"
sasl_user "USER-NAME"
sasl_password "PASSWORD"

To prevent other users from reading this file, set the mode of the file to 0600 or 0400 using the chmod(1) command.

For LOGIN mechanism

sasl_mechanisms "LOGIN"
sasl_user "USER-NAME"
sasl_password "PASSWORD"

To prevent other users from reading this file, set the mode of the file to 0600 or 0400 using the chmod(1) command.

For XOAUTH2 mechanism

sasl_mechanisms "XOAUTH2"
sasl_user "USER-NAME"

By placing the following configuration file named gfarm-client.conf in the Cyrus SASL configuration directory ($(pkg-config --variable=libdir libsasl2)/sasl2), the sasl_user specification can be omitted.

xoauth2_user_claim: key name of claim to be used as user ID in JWT

In that case, since there is no user-specific setting, only sasl_mechanism can be set in gfarm2.conf.

In addition, place the access token used by XOAUTH2 in the file specified by the JWT_USER_PATH environment variable, or in the file /tmp/jwt_user_u<YOUR-UNIX-UID>/token.jwt if the environment variable is not set. To prevent other users from reading this file, set the mode of the JWT file to 0600 or 0400 using the chmod(1) command.

The jwt-logon and jwt-agent commands can be used to obtain a token and set JWT in the appropriate mode for this file.

If the first character of the value set in the JWT_USER_PATH environment variable is '!', the subsequent string is treated as a command and the output of that command is used as an access token for XOAUTH2.

You can also set the JWT contents directly by using the sasl_password directive in the file specified by the GFARM_CONFIG_FILE environment variable, or in the .gfarm2rc file in your home directory if the environment variable is not set. In this case, use the chmod(1) command to set the mode of the file to 0600 or 0400 to prevent other users from reading it.