Configuring multifactor authentication with IBM Security Verify

Edit online

The system integrates with IBM® Security Verify to provide multifactor authentication for system users.

With IBM Security Verify, security administrators can configure the system as an application that requires two factors for users and user groups to access the system with either the management GUI or CLI.

Multifactor authentication can be used to protect both local users, including superuser, and remote users.

Remote users are users who are defined on a remote LDAP server. For remote users that authenticate with LDAP servers, install and configure IBM Security Verify Bridge for Directory Sync on your LDAP server, such as Windows Active Directory. IBM Security Verify Bridge for Directory Sync duplicates any users and groups that are defined on the source LDAP server into the Cloud Directory in IBM Security Verify. Any subsequent changes that are made to the source LDAP server are copied automatically to the Cloud Directory in IBM Security Verify. For more information, see IBM Security Verify Bridge for Directory Sync in the IBM Security Verify documentation.

IBM Security Verify configures the management GUI and the command-line interface as separate API clients that require separate credentials. For GUI-based logins, the system communicates with IBM Security Verify through the OpenID Connect (OIDC) protocol.

Important:

When the system certificate added as the signer certificate expires, you cannot login to the management GUI if you are using multifactor authentication. To export the new system certificate and install it in IBM Security Verify, login using the CLI.

Prerequisites

Ensure that the following prerequisite tasks are completed on the system before you configure multifactor authentication IBM Security Verify:
  1. Ensure the system is updated to 8.5.0 or later release.
  2. Configure a DNS server. To create a DNS server, select Settings > Network > DNS. In the command-line interface, use the mkdnsserver command to define a DNS server.
  3. Configure an HTTP proxy server or configure your firewall to access IBM Security Verify. To create an HTTP proxy server, Settings > Network > Internal Proxy Server. For more information, see Defining an HTTP proxy server. If your system does not directly connect to the Internet, you can create a firewall exception to allow your system access to IBM Security Verify.
    Important: If the proxy server is not configured correctly, the system cannot communicate with IBM Security Verify and the login to the system fails.
  4. For the management GUI and the command-line interface, ensure that the inactivity logout is equal to or greater than the time it takes for a user to receive a one-time passcode (OTP) from the authentication service. The default value for the inactivity timeout is 30 minutes for the management GUI and 15 minutes for the CLI. To set the inactivity timeout for both interfaces in the management GUI, select Settings > Security > Inactivity Logout. To set the GUI inactivity timeout on the command-line interface, use the chsecurity -guitimeout command. For the CLI timeout, use the chsecurity -clitimeout command.
  5. Ensure that the SSH grace time for the command-line interface is equal to or greater than the time it takes for a user to receive a one-time passcode (OTP) from the authentication service. The default value for the SSH grace time period is 60 seconds. To set SSH grace time on the system in the command-line interface, use the chsecurity -sshgracetime command.
The following prerequisite steps on IBM Security Verify must be completed before you can configure multifactor authentication on the system:
  1. Create a subscription for IBM Security Verify. You need an IBMid to create a subscription. A 90-day free trial subscription is also available. For more information, see Cloud identity and access management (IAM) solutions. During subscription creation, you specify a tenant that is used to create a URL to access the IBM Security Verify dashboard.
  2. Access the IBM Security Verify administrator dashboard by entering the following URL in a web browser:
    https://tenant.verify.ibm.com/ui/admin
    Where tenant is the name of the tenant that you specified when you created your subscription. Usually this tenant name is associated with your company or organization.
  3. In the IBM Security Verify interface, select Applications > Applications > Add application.
  4. Select IBM Spectrum Virtualize > Add Application.
    Note: Each system must be added as a separate application.

    The following table shows the required fields and actions for the General tab in the IBM Security Verify interface.

    Table 1. General tab
    Field Action
    Name Enter a name to identify the system on IBM Security Verify. If you are adding multiple systems, enter a unique name.
    Description Enter a brief description of the system.
    Company name Name of organization or company.

    The following table shows the required fields and actions for the Sign-on tab in the IBM Security Verify interface. The Sign-on tab is used to add the management GUI as an API-based client.

    Table 2. Sign-on tab
    Field Action Details
    Application URL Enter the URL for your system. Enter the URL that is used to access the management GUI.
    Grant type Select Authorization code and JWT bearer. Two grant types are required for setting up MFA for the system. Authorization code indicates that the client can request access to protected resources on behalf of users.
    Client ID This value is automatically generated when the system is saved as an application. This value must be entered to the Multifactor authentication page in the management GUI under OpenID Credentials.
    Client secret This value is automatically generated when the system is saved as an application. This value must be entered to the Multifactor authentication page in the management GUI under OpenID Credentials.
    User consent Select Do not ask for consent.  
    Redirect URIs Enter the locations where the authorization server sends users after they are successfully authorized and granted an authorization code or access token. Multiple redirect URIs can be specified for both the management GUI and the service assistant GUI. For management GUI access, the redirect URI is comprised of the management IP address or hostname followed by /mfa. For the service assistant interface, the redirect URI is comprised of the hostname or IP address for the system followed by service/mfa. For example:
    https://hostname.com/mfa
    https://hostname/service/mfa
    JWT bearer user identification Select Username. Indicates that the username field in the JWT bearer is used to find users in the Cloud Directory and determines what second factors IBM Security Verify presents to users when they log into the system.
    JWT bearer default identity source Ensure Cloud Directory is selected. Indicates that the IBM Security Verify Cloud Directory is used to look up the second factor for the username. After you configure multifactor authentication on the system, users and user groups must be added to the Cloud Directory.
    Generate refresh token Ensure that this option is unchecked.  
    Send all known user attributes in the ID token Ensure that this option is checked.  
    Access policies Complete these steps:
    1. Deselect Use default policy.
    2. Click the Edit icon.
    3. Select Always require 2FA in all devices.
    4. Click OK.
    		 This action creates an access policy which controls the authentication steps for system access. Access policies can specify different authentication requirements based on properties of the user or connection. In this case, all users must complete a second factor authentication every time they access the system from all devices.
    Restrict custom scopes Ensure this option is unchecked.  

    The following table shows the required fields and actions for the API access tab in the IBM Security Verify. The API access tab is used to add the command-line interface as an API-based client and create credentials for multifactor authentication access for CLI users. To add the command-line as a separate API client, click Add API client. On the Add API client page, enter the following information:

    Table 3. Add API Client action
    Field Action Details
    Name Enter a name to identify the command line interface as the API client.  
    Select the APIs to which you want to grant access Ensure that all APIs are selected by moving the toggle to display On  
  5. Click Save. After the system is saved as a new application, the Custom Application reloads with the Entitlements tab selected.
  6. On the Entitlements tab, select Automatic access for all users and groups.
  7. Click Save.
  8. Select Applications and select the application name that represents the system.
  9. On the Sign-on tab, copy the Client ID and the Client secret. These values must be specified as the OpenID credentials on the Multifactor authentication page in the management GUI.
  10. On the API access tab, click the edit icon and copy the Client ID and the Client secret. These values must be specified as the API Client credentials on the Multifactor authentication page in the management GUI.

Using the management GUI

To configure multifactor authentication on IBM Security Verify, complete these steps:
  1. Select Settings > Security > Multifactor Authentication.
  2. Enter the host name and port of the authentication server. For IBM Security Verify, enter the following:
    tenant.verify.ibm.com
    Where tenant is the name that is associated with your subscription. Port 443 is the default for the authentication server.
  3. For the OpenID Credentials, add the Client ID and Client Secret that you copied on from the Sign-on tab in the IBM Security Verify interface.
  4. For the API Client Credentials, add the Client ID and Client Secret that you copied on from the API access tab in the IBM Security Verify interface.
  5. On the Multifactor Authentication page, click Export Certificate to export the system certificate to your device. Copy the system ID alias that displays. This value must be used as the friendly name of the certificate in IBM Security Verify.
  6. Access the IBM Security Verify administrator dashboard by entering the following URL in a web browser:
    https://tenant.verify.ibm.com/ui/admin
    Where tenant is the name of the tenant that you specified when you created your subscription. Usually this tenant name is associated with your company or organization.
  7. Select Security > Certificates.
  8. Under Signer certificates, select Add signer certificate.
  9. On the Add signer certificate page, select Add file and navigate to where you exported the certificate on your device.
  10. In the Friendly name field, copy the system ID alias that displays on the Multifactor Authentication page in the management GUI.
  11. Click OK.
  12. Return to the Multifactor Authentication page in the management GUI, and click Save. On the confirmation page, click Confirm to enable multifactor authentication for the system.

Multifactor authentication is enabled for the system. You can configure user groups to use multifactor authentication. Click Navigate to launch the User Groups page.

Using the CLI

Before you can enable multifactor authentication on the system, ensure that the system certificate is exported and added as a signer certificate. If the certificate is not added as a signer certificate, users with multifactor authentication enabled cannot sign in to the management GUI. To export and add the system certificate, complete the following steps:
  1. To view the system ID alias, enter the following command:
    lssystem | grep id_alias
    Note: The system ID alias must be entered in the Friendly name field on the Add Signer Certificate page in the IBM Security Verify interface.
  2. Enter the following command to export the system certificate: 
    chsystemcert -export
    This command exports the system certificate. Download the resulting file /dumps/certificate.pem to your machine and upload to IBM Security Verify. Ensure to add the system ID alias to the Friendly name field. For more information, see steps 7 through 11 in the management GUI section.
  3. To enable multifactor authentication with IBM Security Verify, enter the following command:
    chauthmultifactorverify -hostname tenant.verify.ibm.com -openidclientid yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -openidclientsecret yyyyyyyyyy -cliclientid xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -cliclientsecret xxxxxxxxxx -enable

    In the example, tenant is the tenant name that is associated with your subscription. The values for the -openidclientid and the -openidclientsecret are the Open ID Client and Open ID Secret that are automatically generated when you created your system as a custom application in IBM Security Verify on the Sign-on tab in the IBM Security Verify interface. The values for the -cliclientid and the -cliclientsecret are the API Client ID and API Client Secret that are automatically generated when you created your system as a custom application in IBM Security Verify on the API access tab in the IBM Security Verify interface.