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_group_user: a list of the user ID, the scope, and the issuer
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 sub|https://keycloak.example.com/auth/realms/hpci
xoauth2_group_user: web_read|st.read|https://keycloak.example.com/auth/realms/hpci anon|*|*
xoauth2_issuers: https://keycloak.example.com/auth/realms/hpci https://keycloak.example.org/auth/realms/hpci

Multiple scopes can be specified in `xoauth2_scope`. In that case, any one of them must be satisfied. The same applies to `xoauth2_aud`. xoauth_user_claim specifies the claim used as the username. This claim can be set per issuer. xoauth_group_user specifies a group username by defining the issuer and scope. Wildcards can be used for both issuer and scope. xoauth2_issuers specifies a list of trusted issuers. Failing to configure xoauth2_issuers will result in trusting all issuers, creating a security risk.

For more details, refer to here.

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.

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

To use ANONYMOUS mechanism, create an anonymous user in Gfarm as follows.

% gfuser -c anonymous anon / ""

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 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 value in the JWT is used as the user ID. In this case, the sasl_user setting must be deleted. Additionally, you can specify the user ID via the environment variable (GFARM_SASL_USER). The priority order is GFARM_SASL_USER > sasl_user > xoauth2_user_claim.

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

When specifying the user ID via the xoauth2_user_claim, user-specific configuration is unnecessary, so it is possible to configure only the sasl_mechanism setting system-wide 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.