Performing SSO by using Node

Configure the included Node.js application to perform single sign-on (SSO) with the IBM® MFA server. The included Node.js application allows IBM MFA users to authenticate against an OpenID Connect application to obtain a CTC for use when authenticating to z/OS applications. IBM MFA starts Node.js at IPL time and restarts it if needed.

Before you begin

You must satisfy the following prerequisites:

• Install IBM Open Enterprise SDK for Node.js on the IBM MFA server.

  IBM Open Enterprise SDK for Node.js is a no-charge SDK to connect Node.js applications to z/OS resources. See Options on how to obtain IBM Open Enterprise SDK for Node.js for installation information.

• OpenID Connect-specific prerequisites. You may need to contact your IT department for this information.
  • You must have the OpenID Connect provider hostname, client ID, client secret, and root CA certificate. If you do not already have these values, contact your IT department.
  • The OpenID Connect application must use the following sign-in redirect URL, where mfa_sso_host_location is the hostname of the system where oidcnode is installed. You can contact your IT department to configure this setting.

    https://mfa_sso_host_location:8443/auth/callback

  • The IBM MFA oidcnode implementation depends on the OpenID Connect single sign-on configuration from Using OpenID Connect for single sign-on.
• The oidcnode.Z pax file is included in the /usr/lpp/IBM/azfv2r3/accessories directory of the IBM MFA server installation.
• You must have a single file in .PEM format that contains the CA at the root of trust for the IBM MFA server certificate, and the root CA for the OpenID Connect provider.

Important: Considersations when applying updates

Before you install IBM MFA maintenance that includes changes to the Node app, perform the following steps to preserve any changes and customizations that you have made:

1. Save and rename a copy of the current oidcnode directory. It may contain modifications to package.json, config.json, and other resources inside the bin subdirectory.
2. Unpack the updated oidcnode.Z archive.
3. Change directory (cd) to where you unpacked oidcnode.Z and run the npm i command to install or update dependencies that may have changed.
4. Migrate and confirm parameters from the previous app installation to the new app installation. These may include, but are not limited to, the following:
   • config.json
   • package.json
   • The CA certificates concatenation
5. After confirming the function of the new app installation, delete the copy of the previous app installation.

1. Configure IBM MFA for OpenID Connect single sign-on as described in Using OpenID Connect for single sign-on.
2. Install the IBM Open Enterprise SDK for Node.js package on the IBM MFA server.
3. Unpack the oidcnode.Z pax file. The /sso-node directory is used in this example for demonstration purposes.
   Note: By default, root owns the extracted files. This example changes the group and owner of the extracted files. You can decide which extraction process to follow based on your own environment and security needs. See the pax man page for command options.

   # mkdir /sso-node
   # cd /sso-node
   # pax -rvf oidcnode.Z -o "gname:=USER""uname:=JUSER"
   /oidcnode
   /oidcnode/README.md
   :
   :

4. Change directory (cd) to where you unpacked oidcnode.Z. (The /sso-node/oidcnode directory in the example.)
5. Run the npm i command to install needed dependencies.
   Note: npm is the package manager for the Node JavaScript platform. It puts modules in place so that Node can find them, and manages dependency conflicts intelligently.

   If the npm command is not found, add the location of the node /bin directory to your PATH.

   npm i

   
6. Configure the OIDC Domain URI, OIDC Client Id, OIDC Client Secret, Certificate Key Ring, and Certificate Label settings in Table 1. These fields protect sensitive data for use by the Node.js application.

   The OIDC Domain URI parameter defines the leading (prefix) portion of the .well-known/openid-configuration URI. The field value must begin with https:// and end with a trailing slash (/).

   For example, if the URI is https://dev-sample.com/.well-known/openid-configuration, then the OIDC Domain URI would be https://dev-sample.com/.

7. Optionally, configure JWKS Proxy Enable, Proxy host, and Proxy port to use a JWKS proxy server, as described in Using a JWKS proxy. These fields protect sensitive data for use by the Node.js application.
8. Edit the extracted config.json file (/sso-node/oidcnode/config.json in the example) and add only the following values:

   
       "oidcDomain": "leave blank",
       "oidcClientId": "leave blank",
       "oidcClientSecret": "leave blank",
       "mfaHostNames": ["mfa1.example.com:6789", "mfa2.example.com:6789", "mfa3.example.com:6789"],
       "cacertsFilenameInBinDir": "cacerts.pem"

   Where:

   • The mfaHostname field is an array of one or more host:port values, where the host is the fully-qualified hostname and port is the server authentication port you configured in Table 1. In a SYSPLEX where the RACF database is shared across member LPARs, separate each host:port value by a comma.
     Important: The field values must include only fully-qualified hostnames, and must not begin with http:// or https://.
   • The cacertsFilenameInBinDir field is a single file in .PEM format that contains both the CA at the root of trust for the IBM MFA server certificate, and the root CA for the OpenID Connect provider. This file must be in the oidcnode/bin directory.

     You specified the CA at the root of trust for the IBM MFA server in Configure an AT-TLS profile.

     One way to do this is to use the concatenate (cat) command:

     cat mfa_server_root_ca.pem > cacerts.pem
     
     cat openid_connect_root_ca.pem >> cacerts.pem

9. Define a user for the STARTED task.

   Consider the following example:

   ADDUSER AZNSSO NAME('SSO BATCH') DFLTGRP(STCGROUP) OWNER(STCGROUP) OMVS(UID(value)) NOPASSWORD

   where:

   • AZNSSO is used only for example purposes.
   • OMVS(UID(value)) specifies z/OS UNIX System Services information for the user. The required user access to the $launcherPath$, $nodeHome, and $ssojsPath$ variables, which are described in a subsequent step, is based on the assigned UID and GID values.
10. Define a profile in the STARTED class. To prevent an AT-TLS rule from applying to Node.js and causing errors, the program run from the JCL must not run in the AZF* Jobname space.

    Consider the following example. AZN*.** is used only for example purposes.

    RDEFINE STARTED AZN*.** STDATA(USER(AZNSSO) GROUP(STCGROUP)) 
    SETROPTS RACLIST(STARTED) REFRESH                                                          
    

11. Give the user ID that you created in Step 9 UPDATE access to the profile that protects the PKCS#11 token you created in Configuring a PKCS#11 token. For example:

    PERMIT USER.token_name CLASS(CRYPTOZ) ID(AZNSSO) ACC(UPDATE)

12. Copy the AZNODEJS member of the SAZFSAMP data set in the target library to the PROCLIB from which you run started tasks.
13. Follow the included instructions to edit your copy.
    For example, you might change this section:

    PGM $launcherPath$
    $nodeHome$/bin/node
    $ssojsPath$
    --sensitive-from-env-only

    to something like:

    PGM /usr/lpp/IBM/azfv2r3/bin/azfsso_launch                                 
    /node/bin/node
    /sso-node/oidcnode/bin/sso.js
    --sensitive-from-env-only                         

14. By default, the Node.js app listens on port 8443. You can override the default listener port by setting the HTTPPORT environment variable from the JCL. For example, to change the port to 1234:

    /sso-node/oidcnode/bin/sso.js -HTTPPORT 1234

    
15. Start the started task. For example:

    S AZNODEJS

16. The launcher executable loads the following values into environment variables. sso.js then loads these sensitive configuration values from this environment, and not from config.json.
    • OIDC Domain URI
    • OIDC Client Id
    • OIDC Client Secret
    • Certificate Key Ring
    • Certificate Label
17. The launcher executable loads the following values into environment variables, if configured:
    • Proxy host
    • Proxy port
    
18. Test the fully-qualified hostname where z-mfa-sso is running, at port 8443:

    https://fully_qualified_mfa_sso_host_location:8443

    The following page should display without errors:

    Acquire MFA Cache Token Credential via OIDC
    
    Select an MFA host and enter your mainframe User ID, then Submit the form.
    :
    :
    MFA Host
    SAF User ID

    If you receive an error similar to the following, it indicates that an AT-TLS rule is applying to Node and causing errors:

    There was an error processing the request
    The request for a CTC was rejected by OIDC. Error: write 
    EPROTO 14B3100000000001:error:0A00010B:SSL routines:ssl3_get_record:wrong 
    version number:../../deps/openssl/openssl/ssl/record/ssl3_record.c:355:

    The AZFExcludeNodeRule rule in SAZFSAMP(AZFTTLSX) prevents AT-TLS from conflicting with a job named AZNODEJS, as referenced in the SAMPLIB(AZNODEJS) sample job.

19. A user who attempts to log in must be provisioned for SSO, as described in Activate and deactivate users for OIDC.