# 9.3. Operating system / Domain users

An os authentication method can be used to authenticate users based on the authentication methods provided by the operating system.

## 9.3.1. Introduction

It can also be used to authenticate administrators for the Web Manager service. For this, you will need to explicitly define a group or a set of groups in the manager_allowed_groups configuration options. By default, no administrators are allowed.

Warning

On Unix-like systems, this authentication method can only be used when the SFTPPlus service is started as root.

You can overwrite some of the account's settings (e.g. home folder path), by defining an account of type os inside the configuration file.

The os authentication method will authenticate the following account types:

- Windows Local Accounts on Windows systems.

- Windows Active Directory Accounts, when SFTPPlus runs on a Windows system which is part of a domain.

- Linux accounts with passwords defined in the `/etc/passwd` file or by the Name Service Switch library.

- Linux accounts with passwords defined in the `/etc/shadow` file.

On systems supporting PAM, PAM can also be used for authenticating users with username and password credentials.

On many Unix-like systems, PAM is used for enabling various authentication methods, such as LDAP, PKCS#11 smart cards, or fingerprint authentication.

When the PAM authentication request returns PAM_SUCCESS, the account is authorized. Any response other than PAM_SUCCESS will reject the account.

PAM only handles authentication. The account configuration is retrieved using the same generic OS API.

Note

The SFTPPlus' pam authentication method will only use PAM for the authentication operation. PAM is not used for managing accounts, sessions, or passwords. Please get in touch with us if you need to integrate PAM accounts and session management with SFTPPlus.

## 9.3.2. name

Default value:

  ''

Optional:

  Yes

From version:

  2.10.0

Values:

  - Any text.

Description:

  Human-readable short text used to identify this method.

## 9.3.3. description

Default value:

  ''

Optional:

  Yes

From version:

  2.10.0

Values:

  - Any text.

Description:

  Human-readable text that describes the purpose of this authentication method.

## 9.3.4. type

Default value:

  ''

Optional:

  No

From version:

  2.10.0

Values:

  - application - Application accounts.

  - os - Accounts authenticated by the OS.

  - http - HTTP (unsecured).

  - ip-time-ban - Ban an IP address for a time interval.

  - deny-username - Deny authentication based on usernames.

  - anonymous - Anonymous account authentication.

  - ldap - Authenticate against an LDAP server.

  - local-file - Authenticate the accounts from a separate local file.

  - radius - Authenticate via an RADIUS server.

  - entra-id - Microsoft Entra ID

Description:

  This option specifies the type of the method. Each type has a set of specific configuration options

## 9.3.5. pam_usage

Default value:

  fallback

Optional:

  Yes

Values:

  - fallback

  - exclusive

  - Empty

From version:

  3.3.0

Description:

  Defines how to use PAM for for authenticating accounts using username and password credentials.

  The default mode is fallback. In this mode it will first try to authenticate accounts based on the `/etc/passwd` file. If the password is set in the operating system as one of the following x, NP, *NP* or *, it will continue to authenticate with PAM.

  In exclusive mode, it will exclusively use PAM for username and password authentications.

  Leave it empty to completely disable PAM usage.

  Note

  On Windows, this option is always disabled as SFTPPlus has no support for PAM on this platform.

## 9.3.6. pam_service

Default value:

  login

Optional:

  Yes

Values:

  - Name of a PAM service.

From version:

  3.3.0

Description:

  Name of the PAM service used for account authentication requests.

## 9.3.7. allowed_groups

Default value:

  Empty

Optional:

  No

Values:

  - Empty

  - OS group name

  - ${ALL_OS_GROUPS}

  - Comma-separated list of OS group names.

From version:

  3.35.0

Description:

  Defines an operating system group or a list of OS groups with users that are allowed by this authentication method.

  When this is empty, no OS account is accepted. You need to define a list of group names for which to allow access. For example, if you need to allow all users from the local system, you can typically use the default users group available on both Windows and Linux.

  If you absolutely need to allow access to all OS users from all OS groups, set this to ${ALL_OS_GROUPS}. This should be the only value, and you can't mix ${ALL_OS_GROUPS} with other group names.

  Note

  This configuration takes operating system group names and not SFTPPlus group names.

## 9.3.8. base_groups

Default value:

  Empty

Optional:

  yes

Values:

  - Empty

  - Group UUID.

  - Comma separated list of group UUIDs.

From version:

  4.23.0

Description:

  Defines the SFTPPlus groups that are associated with any authenticated user.

  Leave empty to not have any default group and only use the groups associated via OS configuration.

  The first configured base group is also the primary group.

## 9.3.9. group_association

Default value:

  base-groups

Optional:

  No

Values:

  - base-groups (since 4.23.0)

  - base-and-os-groups (since 4.23.0)

  - group-name

  - group-name-with-default

From version:

  4.11.0

Description:

  Defines how the SFTPPlus groups are associated with authenticated users for which no explicit association is defined inside the SFTPPlus configuration.

  When set to base-groups it will associate an OS user to the list of groups defined by the base_groups option.

  When set to base-and-os-groups it will associate an OS user to the list of groups defined by the base_groups option and any other group that has the same name as one of the groups defined by the allowed_groups option.

  When set to group-name, it will associate the user with the SFTPPlus group having the same name as the operating system group of this user. If the user is a member of multiple OS groups, the first group defined in allowed_groups will be used. If no SFTPPlus group is found with the same name, the authentication fails.

  When set to group-name-with-default, it will try to associate the user with an SFTPPlus group having the same name as the first OS group. It will use the default SFTPPlus group if no SFTPPlus group is found to have the same name as the OS group.

  Note

  When an OS account is explicitly defined inside SFTPPlus configuration the group_association is ignored and the account's groups configuration is used instead.

## 9.3.10. manager_allowed_groups

Default value:

  Empty

Optional:

  Yes

Values:

  - Empty

  - OS group name

  - Comma-separated list of OS group names.

From version:

  3.37.0

Description:

  Defines an operating system group or a list of OS groups with users that are allowed by this method to be used for the Web Manager service.

  When this is empty, any administrators are denied.

  Note

  This configuration takes operating system group names and not SFTPPlus group names.

## 9.3.11. base_roles

Default value:

  Empty

Optional:

  yes

Values:

  - Empty

  - Role UUID.

  - Comma-separated list of role UUIDs.

From version:

  4.27.0

Description:

  Defines the SFTPPlus roles that are associated with any authenticated administrator.

  Leave empty to not have any default role and only use the roles associated via OS configuration.

  The first configured role is also the primary role.

## 9.3.12. role_association

Default value:

  base-roles

Optional:

  No

Values:

  - base-roles

  - base-and-os-groups

From version:

  4.11.0

Description:

  Defines how the SFTPPlus roles are associated with authenticated administrators.

  When set to base-roles it will associate the administrator to the list of roles defined by the base_roles option.

  When set to base-and-os-groups it will associate an administrator to the list of roles defined by the base_roles option and any other role that has the same name as one of the groups defined by the manager_allowed_groups option.

## 9.3.13. Windows Domain Accounts

When SFTPPlus is installed on a machine belonging to a Domain Controller, it can be configured to allow accounts from a Domain Controller to access the files located on the server. These accounts are authenticated using the os authentication method.

For Domain Controller accounts, there is the option for the username to be provided in the user principal name (UPN) format:

    USERNAME@EXAMPLE.COM

To specify the domain, you should use UPN format, not the legacy NebBIOS names.

Note

Active Directory accounts are only available when SFTPPlus is running on a Windows operating system. If you want to allow Active Directory accounts to access an SFTPPlus instance running on Unix-like systems, please contact our support team.

9.2. SFTPPlus embedded users
9.4. HTTP web service