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.

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. You can install IBM Open Enterprise SDK for Node.js on any z/OS system that satisfies the package prerequisites and has network connectivity to the IBM MFA server.
3. Copy (scp) the oidcnode.Z file from the /usr/lpp/IBM/azfv2r3/accessories directory of the IBM MFA server to the system where you installed the IBM Open Enterprise SDK for Node.js package.
4. 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
   :
   :

5. Edit the extracted config.json file (/sso-node/oidcnode/config.json in the example) and add the following values:

   
       "oidcDomain": "https://OpenID Connect provider hostname/",
       "oidcClientId": "value",
       "oidcClientSecret": "value",
       "mfaHostNames": ["mfa1.example.com:6789", "mfa2.example.com:6789", "mfa3.example.com:6789"],
       "cacertsFilenameInBinDir": "cacerts.pem"
   
   

   Where:

   • oidcDomain is the OpenID Connect provider hostname.
     Important: The field value must begin with https:// and end with a trailing slash (/).
   • oidcClientId and oidcClientSecret are the OpenID Connect provider client ID and client secret, respectively.
   • 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 the CA at the root of trust for the IBM MFA server certificate. This file must be in the oidcnode/bin directory. You specified this CA certificate in Configure an AT-TLS profile.
6. Copy (scp) your server certificate and private key to the bin directory of where you unpacked the oidcnode.Z file. (The /sso-node/oidcnode/bin directory in the example.) You must use the file names server.crt and server.key, respectively.
   Remember that this certificate and private key are for use with the included Node.js application and do not need to be in the IBM MFA server's RACF key ring.
7. Change directory (cd) to the directory where you unpacked the oidcnode.Z file, /sso-node/oidcnode in the example.
8. 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

9. Run the npm i -g pm2 command to install the pm2 Node.js application globally.

   npm i -g pm2

10. Run the npm run start command.

    npm run start
    > z-mfa-sso@0.0.0 start
    > pm2 start ./bin/sso.js --name z-mfa-sso
    :
    

    Tip: The default port is 8443, but you can change this if needed:

    HTTPPORT=port pm2 start z-mfa-sso
    OR....
    pm2 start z-mfa-sso -- -HTTPPORT port

    Trouble: If you do not see the message "Done" and the status, press Ctrl+C to exit and run the npm run start command a second time.

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

    Error: Error: write EPROTO 14C1D00000000001:error:0A00010B:SSL routines:ssl3_get_record:wrong ve
    rsion number:../../deps/openssl/openssl/ssl/record/ssl3_record.c:355:

11. Ensure that z-mfa-sso started:

    pm2 status z-mfa-sso

    
     id  name           mode     ↺    status   cpu     memory
     0   z-mfa-sso      fork    174…  online   0%      nullb 
    

12. If needed, you can stop z-mfa-sso:

    pm2 stop z-mfa-sso

13. 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:

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