Documentation

9.7. Azure Active Directory

The azure-ad method is used to implement single sign-on authentication based on the Azure Active Directory service.

9.7.1. Introduction

To integrate SFTPPlus with the online Azure Active Directory, you will need to set the Azure AD details in SFTPPlus, and the SFTPPlus ones in the Azure AD configuration. In this way, SFTPPlus and Azure AD will be aware of each other and will work together.

Azure AD provides both authentication and authorization processes. For SFTPPlus integration, Azure AD is primarily used for authentication. You will define the authorization rules inside the SFTPPlus configuration. It is recommended to configure the Azure AD authentication method as the first method in your authentication chain, before the SFTPPlus Application Accounts authentication.

The Azure AD authentication process handles identifying and validating the access from an account/user/person. The SFTPPlus authorization process handles the set of file access permissions for the authenticated user.

Note

Only Azure AD public cloud is supported for now. If you use Azure cloud for US Gov, China, or Germany get in touch with us for more information.

From Azure AD you can configure it to allow authentication for all Azure AD users, for an explicit set of Azure AD users, or only for Azure AD users that are associated with SFTPPlus groups having the same name as the Azure AD security group.

SFTPPlus will always ask to confirm the selected Azure AD user for authentication. Get in touch if you would like SFTPPlus to automatically use the active Azure AD user without a prompt.

When the user signs out (logout) from SFTPPlus only the SFTPPlus session is finalized. The Azure AD authentication session is kept and the user is not automatically signed out from Azure AD. This allows the user to access SFTPPlus without entering the password again. Also, if the user is already signed in to Azure AD, authenticating to SFTPPlus will not trigger a new Azure AD authentication process. Some extra authentication steps might be required, depending on your security policy. For example, you might need to confirm a multi-factor authentication request.

The Azure AD authentication process should finalize in less than 2 minutes. For security reasons, SFTPPlus will reject delayed authentication requests.

For SFTPPlus to integrate with the Azure AD authentication, it needs to be able to initiate outgoing connections to the Microsoft/Azure Cloud over HTTPS port 443. Make sure your firewall allows outgoing connections. An HTTP proxy can be used by SFTPPlus to connect to the Azure Cloud. Below is the list of services used by SFTPPlus to communicate with Azure Cloud:

  • login.microsoftonline.com

  • graph.microsoft.com

Note

Only HTTPS file transfer user authentication and web management console are supported. Get in touch if you need to authenticate SFTP users, FTPS users, or administrators using Azure AD.

9.7.2. Azure AD app configuration

Besides defining the Azure AD authentication method inside the SFTPPlus configuration, you will also need to define SFTPPlus inside your Azure AD directory.

Start by adding SFTPPlus to your Azure AD, by using the App registrations page from Azure.

SFTPPlus interacts with Azure AD as an OpenID Connect and OAuth2 application.

Use New registration, define a name (ex SFTPPlus) and select Single tenant.

Redirect URI is required for SFTPPlus operation. Select Web and define the URL using the following format, where SERVER:PORT will be replaced with the address for your HTTPS web file browser, and AUTH-UUID with the unique ID of this authentication method: https://SERVER.COM:PORT/?redirect-AUTH-UUID

Note

Only single-tenant authentication is supported. Only a single Azure AD authentication method can be enabled for one HTTPS file transfer server. When multiple Azure AD authentications are defined, only the first one is used. Get in touch if you need support for multitenant or personal Microsoft accounts.

Once the SFTPPlus application is registered inside Azure you can optionally configure the logout URL. From Essentials -> Redirect URIs, define the front-channel logout URL: https://SERVER.COM:PORT/__chsps__/logout

No application secret is required. SFTPPlus will use the Azure public keys to validate the ID and access tokens.

From the Azure AD App registrations Authentication page, the following options need to be enabled to allow the SFTPPlus to authenticate the Azure AD users. From the Implicit grant and hybrid flows section:

  • Access tokens (used for implicit flows)

  • ID tokens (used for implicit and hybrid flows)

To associate Azure AD groups with SFTPPlus groups, the GroupMember.Read.All API permissions will be requested. No explicit API permissions configuration is required. Azure AD will ask each user to confirm the permissions.

For manual configuration, the following API permissions are required. All permissions are Delegated:

  • openid - for generic authentication

  • User.Read - for generic authentication

  • GroupMember.Read.All - Delegated (for Azure AD group association)

Other configuration options are available in Azure AD via the Enterprise applications page. On the Enterprise applications -> Properties you can configure a general 'Enable/Disable' option for the SFTPPlus application. Assignment required? configuration is important and it defines whether access to SFTPPlus is allowed by default to all your Azure AD users, or you need to grant explicit access to SFTPPlus for Azure AD users.

From the Enterprise applications -> Users and groups page, you can grant explicit access to SFTPPlus to your Azure AD users.

9.7.3. name

Default value:

''

Optional:

Yes

From version:

2.10.0

Values:

  • Any text.

Description:

Human-readable short text used to identify this method.

9.7.4. 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.7.5. 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.

  • azure-ad - Azure Active Directory

Description:

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

9.7.6. directory_id

Default value:

Empty

Optional:

No

Values:

  • Text

From version:

4.22.0

Description:

Directory (tenant) ID of the SFTPPlus inside the Azure AD. This value can be viewed after registering SFTPPlus in Azure AD via the App registrations page.

9.7.7. application_id

Default value:

Empty

Optional:

No

Values:

  • Text

From version:

4.22.0

Description:

Application (client) ID of the SFTPPlus inside the Azure AD. This value is obtained after registering SFTPPlus in Azure AD via the App registrations page.

9.7.8. base_groups

Default value:

Empty

Optional:

yes

Values:

  • Empty

  • Group UUID.

  • Comma-separated list of group UUIDs.

From version:

4.22.0

Description:

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

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

The first configured base group is also the primary group.

9.7.9. group_association

Default value:

base-groups

Optional:

No

Values:

  • base-groups

  • base-and-azure-groups

From version:

4.22.0

Description:

Defines the SFTPPlus groups that are associated with authenticated users.

When set to base-groups, it will associate any Azure AD user with the list of groups configured via the base_groups configuration option.

When set to base-and-azure-groups, it will associate the user with the list of groups defined via the base_groups option and the SFTPPlus groups having the same name as the Azure AD security groups that this user is a member of. If the user is associated with Azure AD groups not configured on SFTPPlus, those groups are ignored. If no Azure AD groups are found for this user, only the base groups are used. If the authenticated user has no associated SFTPPlus group in Azure AD and base_groups is empty, the authentication fails. The Azure AD groups are associated with SFTPPlus groups if they have the same name. The matching is case-sensitive.

9.7.10. 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.

The first configured base role is also the primary role.

Danger

When this option is defined (not empty), any Azure AD user that is accepted as part of the SFTPPlus Azure AD app registration is allowed to connect to the SFTPPlus management web console.

We recommend creating an Azure AD app registration dedicated to the SFTPPlus management web console, separate from the Azure AD app dedicated to file transfers.

You can then configure access to SFTPPlus management, via the Azure Portal. From Azure AD -> Enterprise applications search for the registered SFTPPlus Azure AD app, and from the Users and Groups configure the access.

9.7.11. proxy

Default value:

''

Optional:

Yes

Values:

  • URI like expression.

  • connect://12.342.421.2:3128

From version:

4.23.0

Description:

This configures the proxy used by SFTPPlus to connect to the cloud services required by Azure AD.

For now, only the HTTP/1.1 CONNECT tunneling proxy method is supported.

9.7.12. remove_username_suffix

Default value:

Empty

Optional:

Yes

Values:

  • Text

  • Multiple values, one value per line.

From version:

4.23.0

Description:

Suffix of the Azure AD username to be removed by SFTPlus when generating the username used for file transfer operations.

You can configure SFTPPlus to remove multiple suffixes. Define each suffix that should be removed on a separate line. The first suffix matching the Azure AD username is used, while the remaining are ignored.

For example, if the Azure AD username is Jane.R@sftpplus.onmicrosoft.com, and you want SFTPPlus to handle the user as Jane.R, you can configure this as remove_username_suffix = @sftpplus.onmicrosoft.com.

9.7.13. api_scopes

Default value:

Empty

Optional:

Yes

Values:

  • Azure API scope name

  • Multiple scope names, one scope per line.

From version:

4.24.0 This allows SFTPPlus to ask the Azure AD for extra API permissions when an account is authenticated.

The extra API access token is available to the SFTPPlus Python API extensions. It is used for implementing custom extensions that integrate with Azure AD.

You can leave this empty if you don't plan to use custom SFTPPlus extensions.

Multiple API scopes can be defined. Each scope should be defined on a separate line.

9.7.14. password

Default value:

Empty

Optional:

Yes

Values:

  • plain text

From version:

4.24.0 This is the Azure client secret generated for the SFTPPlus application.

This is only required if you configure api_scopes.

When api_scopes is not configured, this value is ignored and not used.

9.6. LDAP / Active Directory
9.8. RADIUS