5.1. Authentication methods

5.1.1. Introduction

SFTPPlus provides multiple ways in which an account or administrator can be authenticated.

Here are a few methods / sources used to authenticate accounts. For a full list please check the authentication methods configuration:

• Operating System Local Account
• Active Directory
• SFTPPlus own accounts persisted in a configuration file
• SFTPPlus WebAdmin accounts
• HTTP resource

These accounts can be authenticated by various types of credentials. Below is a list of supported credentials:

• user name and password provided by the operating system
• user name and password provided in a configuration file
• user name and SSH RSA/DSA keys
• user name and SSL certificates.

Note

SSH RSA/DSA keys credentials are only available when used with SFTP.

SSL certificate credentials are only available when used with FTPS.

On the Windows operating system, SSH RSA/DSA key and SSL certificates credentials are only available for application accounts, i.e. Windows local or Active Directory accounts can be authenticated only based on user name and password credentials.

While supporting multiple authentication methods and hence multiple account identity providers, there is the risk of overlapping account names / IDs, the same account being provided by multiple sources.

The server will check each authentication method in the configured order and will stop checking other providers at the first source accepting or rejecting the credentials. If the source cannot give an accept / reject answer, since the account name / ID is unknown, the server will ask the next identity source provider.

5.1.2. HTTP / HTTPS methods

When an HTTP or HTTPS method is used, SFTPPlus will initiate an HTTP POST client request to the configured URL and use the response to authenticate the account.

Request and response are both Unicode, encoded in UTF-8.

5.1.2.1. Request

For a password-based authentication to an SFTP service from a remote client originating at 12.442.23.34:2345 and requesting authentication of the user as kevin with password home-alone, the request is:

POST /remote/url
Content-Type: application/json

{
  "credentials": {
    "type": "password",
    "username": "kevin",
    "content": "home-alone",
    "peer": {
      "address": "12.442.23.34",
      "port": 2345",
      "protocol": "TCP"
      },
    "creator": {
      "uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
      "type": "ssh"
      }
    },
  "server": {
    "uuid": "cc5c804d-0a3c-4c4c-b651-eba6fc3b5902"
    }
  }
}

For the same client, but this time using SSH keys authentication, the request is:

POST /remote/url
Content-Type: application/json

{
  "credentials": {
    "type": "ssh-key",
    "username": "kevin",
    "content": "AAAAB3NzaC1yc2EAAAADAQABAAABAQChBpRFG9wXkaKEY-CONTENT",
    "peer": {
      "address": "12.442.23.34",
      "port": 2345",
      "protocol": "TCP"
      },
    "creator": {
      "uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
      "type": "ssh"
      }
    },
  "server": {
    "uuid": "cc5c804d-0a3c-4c4c-b651-eba6fc3b5902"
    }
}

For the same client, but this time using SSL certificate authentication, the request is:

POST /remote/url
Content-Type: application/json

{
  "credentials": {
    "type": "ssl-certificate",
    "username": "kevin",
    "content": "-----BEGIN CERTIFICATE-----\\nMIIG8TCCBN-PEM-FORMAT",
    "peer": {
      "address": "12.442.23.34",
      "port": 2345",
      "protocol": "TCP"
      },
    "creator": {
      "uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
      "type": "https"
      }
    },
  "server": {
    "uuid": "cc5c804d-0a3c-4c4c-b651-eba6fc3b5902"
    }
}

5.1.2.2. Success response

For a successful authentication, the server should respond with HTTP code 204:

Status: 204 Authenticated

The response can also include an optional body containing account configuration. In this case, the response should be 200:

Status: 200 OK

{
  "account": {
    "home_folder_path": "/local/path/for/account",
    "uuid": "ebfbee04-17be-4d9f-b7fc-20ffed6a61a8",
    "create_home_folder": true,
    "create_home_folder_owner": "ude_team",
    "create_home_folder_group": "partners"
    }
}

All values are case-sensitive, and keys should be lower-case.

An error is flagged when a response contains unknown keys.

---

name:home_folder_path type:string optional:Yes default:Configuration from default group. description:Absolute path used as root folder for this account.

---

name:uuid type:string optional:Yes default:Account/User name description:UUID of this account, can be used to track renamed accounts.

---

group:group type:string optional:Yes default:DEFAULT_GROUP. description:UUID of the SFTPPlus group associated with this account.

---

name:create_home_folder type:boolean optional:Yes default:Configuration from default group. description:When true, it will create missing home folder.

---

name:create_home_folder_owner type:string optional:Yes default:Configuration from default group. description:OS account used as owner for the new home folder.

---

name:create_home_folder_group type:string optional:Yes default:Configuration from default group. description:OS group attached to the new home folder.

5.1.2.3. Rejected credentials or disallowed accounts

When an account or its credentials are not accepted, but can be authenticated using other methods, the server should respond with HTTP code 401 and a short error message:

Status: 401 Unauthorized or Human readable text for the error.

When an account or its credentials are rejected, the server should not try to authenticate using another method, the response should display HTTP code 403 and a short error message:

Status: 403 Forbidden or Human readable text for the error.

5.1.2.4. Connection failures and invalid response

When you cannot get a response from the remote HTTP server (e.g. network failures, remote resource not found, etc.) or a response is invalid, SFTPPlus will consider the account disallowed, and will not try to authenticate the account using other methods.