Configuring Authentication in Your iSCSI-Based Storage Network

Setting up authentication for your iSCSI devices is optional.

In a secure environment, authentication is not required because only trusted initiators can access the targets.

In a less secure environment, the target cannot determine if a connection request is truly from a given host. In that case, the target can authenticate an initiator by using the Challenge-Handshake Authentication Protocol (CHAP).

CHAP authentication uses the notion of a challenge and response, which means that the target challenges the initiator to prove its identity. For the challenge/response method to work, the target must know the initiator's secret key, and the initiator must be set up to respond to a challenge. Refer to the array vendor's documentation for instructions on setting up the secret key on the array.

iSCSI supports unidirectional and bidirectional authentication as follows:

• Unidirectional authentication enables the target to authenticate the identity of the initiator. Unidirectional authentication is done on behalf of the target to authenticate the initiator.

• Bidirectional authentication adds a second level of security by enabling the initiator to authenticate the identity of the target. Bidirectional authentication is driven from the initiator, which controls whether bidirectional authentication is performed. The only setup required for the target is that the chap user and chap secret must be correctly defined.

How to Configure CHAP Authentication for Your iSCSI Initiator

This procedure assumes that you are logged in to the local system where you want to securely access the configured iSCSI target device.

• The length of the CHAP secret key for the COMSTAR iSCSI target must be a minimum of 12 characters and a maximum of 255 characters. Some initiators support only a shorter maximum length for the secret key.

• Each node identifying itself using CHAP must have both a user name and a password. In the Oracle Solaris OS, the CHAP user name is set to the initiator or target node name (that is, the iqn name) by default. The CHAP user name can be set to any length of text that is less than 512 bytes. The 512-byte length limit is an Oracle Solaris limitation. However, if you do not set the CHAP user name, it is set to the node name upon initialization.

You can simplify CHAP secret key management by using a third-party RADIUS server, which acts as a centralized authentication service. When you use RADIUS, the RADIUS server stores the set of node names and matching CHAP secret keys. The system performing the authentication forwards the node name of the requester and the supplied secret of the requester to the RADIUS server. The RADIUS server confirms whether the secret key is the appropriate key to authenticate the given node name. Both iSCSI and iSER support the use of a RADIUS server.

For more information about using a third-party RADIUS server, see Using a Third-Party RADIUS Server to Simplify CHAP Management in Your iSCSI Configuration.

1. Become an administrator.

   For more information, see How to Use Your Assigned Administrative Rights in Oracle Solaris 11.1 Administration: Security Services.

2. Determine whether you want to configure unidirectional or bidirectional CHAP.

   • Unidirectional authentication, the default method, enables the target to validate the initiator. Complete steps 3–5 only.

   • Bidirectional authentication adds a second level of security by enabling the initiator to authenticate the target. Complete steps 3–9.

3. Unidirectional CHAP: Set the secret key on the initiator.

   The following command initiates a dialogue to define the CHAP secret key:

   initiator# iscsiadm modify initiator-node --CHAP-secret
   Enter CHAP secret: ************
   Re-enter secret: ************

4. (Optional) Unidirectional CHAP: Set the CHAP user name on the initiator.

   By default, the initiator's CHAP user name is set to the initiator node name.

   Use the following command to use your own initiator CHAP user name:

   initiator# iscsiadm modify initiator-node --CHAP-name new-CHAP-name

5. Unidirectional CHAP – Enable CHAP authentication on the initiator.

   initiator# iscsiadm modify initiator-node --authentication CHAP

   CHAP requires that the initiator node have both a user name and a password. The user name is typically used by the target to look up the secret key for the given user name.

6. Select one of the following to enable or disable bidirectional CHAP.

   • Enable bidirectional CHAP for connections with the target.

     initiator# iscsiadm modify target-param -B enable target-iqn

   • Disable bidirectional CHAP.

     initiator# iscsiadm modify target-param -B disable target-iqn

7. Bidirectional CHAP: Set the authentication method to CHAP for the target.

   initiator# iscsiadm modify target-param --authentication CHAP target-iqn

8. Bidirectional CHAP: Set the target device secret key that identifies the target.

   The following command initiates a dialogue to define the CHAP secret key:

   initiator# iscsiadm modify target-param --CHAP-secret target-iqn

9. Bidirectional CHAP: If the target uses an alternate CHAP user name, set the CHAP name that identifies the target.

   By default, the target's CHAP name is set to the target name.

   You can use the following command to change the target's CHAP name:

   initiator# iscsiadm modify target-param --CHAP-name target-CHAP-name

How to Configure CHAP Authentication for Your iSCSI Target

This procedure assumes that you are logged in to the local system that contains the iSCSI targets.

1. Become an administrator.
2. Determine whether you want to configure unidirectional or bidirectional CHAP.

   • Unidirectional authentication is the default method. Complete steps 3–5 only.

   • For bidirectional authentication. Complete steps 3–7.

3. Unidirectional/Bidirectional CHAP: Configure the target to require that initiators identify themselves using CHAP.

   target# itadm modify-target -a chap target-iqn

4. Unidirectional/Bidirectional CHAP: Create an initiator context that describes the initiator.

   Create the initiator context with the initiator's full node name and with the initiator's CHAP secret key.

   target# itadm create-initiator -s initiator-iqn
   Enter CHAP secret: ************
   Re-enter secret: ************

5. Unidirectional/Bidirectional CHAP: If the initiator uses an alternate CHAP name, then configure the initiator-context with the alternate name.

   target# itadm modify-initiator -u initiator-CHAP-name initiator-iqn

6. Bidirectional CHAP: Set the target device secret key that identifies this target.

   target# itadm modify-target -s target-iqn
   Enter CHAP secret: ************
   Re-enter secret: ************

7. (Optional) Bidirectional CHAP: If the target uses an alternate CHAP user name other than the target node name (iqn), modify the target.

   target# itadm modify-target -u target-CHAP-name target-iqn

Using a Third-Party RADIUS Server to Simplify CHAP Management in Your iSCSI Configuration

You can use a third-party RADIUS server that acts as a centralized authentication service to simplify CHAP key secret management. With this method, the recommended practice is to use the default CHAP name for each initiator node. In the common case when all initiators are using the default CHAP name, you do not have to create initiator contexts on the target.

How to Configure a RADIUS Server for Your iSCSI Target

You can use a third-party RADIUS server that acts as a centralized authentication service to simplify CHAP key secret management. With this method, the recommended practice is to use the default CHAP name for each initiator node. In the common case when all initiators are using the default CHAP name, you do not have to create initiator contexts on the target.

This procedure assumes that you are logged in to the local system where you want to securely access the configured iSCSI target device.

1. Become an administrator.
2. Configure the initiator node with the IP address and the port of the RADIUS server.

   The default port is 1812. This configuration is completed once for all iSCSI targets on the target system.

   initiator# itadm modify-defaults -r RADIUS-server-IP-address
   Enter RADIUS secret: ************
   Re-enter secret: ************

3. Configure the shared secret key that is used for communication between the target system and the RADIUS server.

   initiator# itadm modify-defaults -d
   Enter RADIUS secret: ************
   Re-enter secret: ************

4. Configure the target system to require RADIUS authentication.

   This configuration can be performed for an individual target or as a default for all targets.

   initiator# itadm modify-target -a radius target-iqn

5. Configure the RADIUS server with the following components:

   • The identity of the target node (for example, its IP address)

   • The shared secret key that the target node uses to communicate with the RADIUS server

   • The initiator's CHAP name (for example, it's iqn name) and the secret key for each initiator that needs to be authenticated

How to Configure a RADIUS Server for Your iSCSI Initiator

You can use a third-party RADIUS server that acts as a centralized authentication service to simplify CHAP secret key management. This setup is only useful when the initiator is requesting bidirectional CHAP authentication. You must still specify the initiator's CHAP secret key, but you are not required to specify the CHAP secret key for each target on an initiator when using bidirectional authentication with a RADIUS server. RADIUS can be independently configured on either the initiator or the target. The initiator and the target do not have to use RADIUS.

1. Become an administrator.
2. Configure the initiator node with the IP address and the port of the RADIUS server.

   The default port is 1812.

   # iscsiadm modify initiator-node --radius-server ip-address:1812

3. Configure the initiator node with the shared secret key of the RADIUS server.

   The RADIUS server must be configured with a shared secret for iSCSI to interact with the server.

   # iscsiadm modify initiator-node --radius-shared-secret
   Enter secret:
   Re-enter secret

4. Enable the use of the RADIUS server.

   # iscsiadm modify initiator-node --radius-access enable

5. Set up the other aspects of CHAP bidirectional authentication.

   # iscsiadm modify initiator-node --authentication CHAP
   # iscsiadm modify target-param --bi-directional-authentication enable target-iqn
   # iscsiadm modify target-param --authentication CHAP target-iqn

6. Configure the RADIUS server with the following components:

   • The identity of this node (for example, its IP address)

   • The shared secret key that this node uses to communicate with the RADIUS server

   • The target's CHAP name (for example, its iqn name) and the secret key for each target that needs to be authenticated

Oracle Solaris iSCSI and RADIUS Server Error Messages

This section describes the error messages that are related to an Oracle Solaris iSCSI and RADIUS server configuration. Potential solutions for recovery are also provided.

empty RADIUS shared secret

Cause: The RADIUS server is enabled on the initiator, but the RADIUS shared secret key is not set.

Solution: Configure the initiator with the RADIUS shared secret key. For more information, see How to Configure a RADIUS Server for Your iSCSI Target.

WARNING: RADIUS packet authentication failed

Cause: The initiator failed to authenticate the RADIUS data packet. This error can occur if the shared secret key that is configured on the initiator node is different from the shared secret key on the RADIUS server.

Solution: Reconfigure the initiator with the correct RADIUS shared secret. For more information, see How to Configure a RADIUS Server for Your iSCSI Target.