Using an external authentication server

The following versions of external authentication servers are supported:

• OpenLDAP: 2.4

• Windows Server (Active Directory): 2012 R2, 2016, 2019

TLS protocols available:

• LDAPS

• StartTLS

To use a TLS protocol, you must set isStartTlsEnabled, primaryLdapServerUrl, and secondaryLdapServerUrl in the external authentication server settings according to the following table:

When users are not managed on a group basis on the external authentication server:

A user is authenticated by using the user group information registered in VSP One SDS Block. The external authentication server is used as follows in VSP One SDS Block. After setting a link with the external authentication server, create a user locally in VSP One SDS Block by using the same user name (user ID) registered in the external authentication server. Hereinafter, these users might be called external users.

(Example) Alice, an external user, belongs to a built-in user group AuditAdministrators that has the Audit role.

She can download audit log files (required for the Audit role) by running the GET /v1/objects/audit-logs/download command with Alice specified for the user name and her password specified.

In this case, the external authentication server confirms that Alice has specified the correct password. VSP One SDS Block obtains the group from the user to which the external authentication server responded, obtains a role from the group, and then grants access after comparing the role to that required for access to URL /v1/objects/audit-logs/download.

The user Alice and group AuditAdministrators must be registered in VSP One SDS Block. Her password does not need to be registered.

The case in which users are not managed on a group basis on the external authentication server is called an external authentication and local authorization use case. This use case corresponds to the case in which the REST API (CLI) is run with "User" specified for the mappingMode (CLI: --mapping_mode) parameter in PATCH /v1/objects/external-auth-server-setting (CLI: external_auth_server_setting_set).

When users are managed on a group basis on the external authentication server:

This use case is supported when the external authentication server is Active Directory. A user is authenticated by using the user group information registered in the external authentication server. It is assumed that the external user belongs to a group of external authentication servers. In VSP One SDS Block, set the link with the external authentication server, create a user group locally in VSP One SDS Block, and then set the name of the external group in a parameter. In this case, you do not have to create a user individually. Hereinafter, these user groups might be called external groups.

(Example) Alice (a user) belongs to a CorporateAuditAdministrators group defined in an external authentication server.

In this case, whether Alice specified a correct password and belongs to a CorporateAuditAdministrators group are verified by an external authentication server. VSP One SDS Block obtains the role from the group to which the external authentication server responded, and then grants access after comparing the role to that required for access to URL /v1/objects/audit-logs/download.

The user Alice does not need to be registered in VSP One SDS Block. However, the group CorporateAuditAdministrators must be registered. More specifically, run the POST /v1/objects/user-groups (CLI: user_group_create) command with a user group corresponding to CorporateAuditAdministrators specified for the externalGroupName (CLI: --external_group_name) parameter.

The case in which users are managed on a group basis on the external authentication server is called an external authentication and external authorization use case. This use case corresponds to the case in which the REST API (CLI) is run with "Group" specified for the mappingMode (CLI: --mapping_mode) parameter in PATCH /v1/objects/external-auth-server-setting (CLI: external_auth_server_setting_set).

Each time an external authentication server is used, an inquiry is made to the external authentication server (in basic authentication) to verify the latest information. In session authentication, no inquiry is made to the external authentication server, but authentication is performed just by verifying if the token is valid.

How to use mappingMode with VSP One SDS Block

When OpenLDAP is used as the external authentication server, "Group" cannot be used in mappingMode (CLI: --mapping_mode). This is because OpenLDAP does not support operations of searching groups to which users belong.

When Active Directory is used as the external authentication server, you can specify either "User" or "Group" in mappingMode (CLI: --mapping_mode). When the group of Active Directory corresponds to the role of VSP One SDS Block, use "Group" in mappingMode (CLI: --mapping_mode). If the group of Active Directory does not correspond to the role of VSP One SDS Block, use "User" in mappingMode (CLI: --mapping_mode).

• Example of a case in which the use of "Group" in mappingMode (CLI: --mapping_mode) is appropriate

  A user called Alice belongs to the CorporateAuditAdministrators group of Active Directory. The members of the group have the Audit role of VSP One SDS Block. In such a case, if "Group" is used in mappingMode (CLI: --mapping_mode), managing user passwords or affiliation between a user and group by VSP One SDS Block is unnecessary, and unified management by Active Directory is possible.

• Example of a case in which the use of "User" in mappingMode (CLI: --mapping_mode) is appropriate

  A user (called Alice) belongs to a sales branch group of Active Directory. Another user (called Bob) belongs to an accounting branch group. If you want to assign an Audit role of VSP One SDS Block to Alice and Bob, "User" is appropriate to be used in mappingMode (CLI: --mapping_mode) because there is no relation between the group of Active Directory and the role of VSP One SDS Block. For this reason, make those two users belong to an AuditAdministrators built-in user group of VSP One SDS Block. By doing so, unified management by Active Directory without management of user passwords by VSP One SDS Block becomes possible.

Setting example of an external authentication server

This example assumes the condition that a Windows server is used as an external authentication server and users are managed on a group basis on the external authentication server.

Active Directory is in the following directory configuration.

The following shows an example of parameter settings for PATCH /v1/objects/external-auth-server-setting (CLI: external_auth_server_setting_set).

VSP One SDS Block does not perform recursive search when searching users and groups on an external authentication server. For this reason, users and groups that VSP One SDS Block refer to must be directly under userTreeDn (CLI: user_tree_dn) and userGroupTreeDn (CLI: user_group_tree_dn), respectively.

The user account to be specified for bindDn (CLI: bind_dn) must have privileges to view all entries under userTreeDn (CLI: user_tree_dn) and userGroupTreeDn (CLI: user_group_tree_dn). This account does not have to be under userTreeDn (CLI: user_tree_dn).

Appropriate values for userObjectClass (CLI: user_object_class) and userGroupObjectClass (CLI: user_group_object_class) differ depending on external authentication servers that you are using. To confirm schema settings of your external authentication server, you must view the existing users and groups under baseDn (CLI: base_dn) by using a Linux ldapsearch command or Windows ldp.exe.

(Example) The following long command has line feeds delimited by "\". You can copy and paste command lines including "\" for normal operation.

$ ldapsearch -D <bind_dn> \
 -w <bind_dn_password> \
 -H <primary_ldap_server_url> \
 -b <base_dn> \
 "(objectClass=*)"

To verify whether connection with an external authentication server can be established by using ldapsearch command, use the following command: POST/v1/objects/external-auth-server-setting/actions/verify-connectivity/invoke (CLI: external_auth_server_setting_verify_connectivity). The following is an example of the command that is issued in such a case. If the preceding command execution does not succeed, running the following command on a Linux server might help to identify the cause of the failure. Adding the -d 1 option displays traces for debug, which might help with resolving the problem.

(Example) The following long command has line feeds delimited by "\". You can copy and paste command lines including "\" for normal operation.

$ ldapsearch -D <bind_dn> \
 -w <bind_dn_password> \
 -H <primary_ldap_server_url> \
 -b <user_tree_dn> \
 "(&(objectClass=<user_object_class>)(<user_id_attribute>=*))" \
 <user_id_attribute>