Generating a JSON Web Key for IRS Connection

The U.S. Internal Revenue Service (IRS) uses the Information Returns Intake System (IRIS) to receive forms submitted by Issuers, Transmitters, and Software developers. To submit forms through the IRS IRIS’s Application-to-Application (A2A) service, an API Client ID is required.

This section describes how to use PeopleSoft PeopleTools to generate a JSON Web Key (JWK), which is needed to obtain an API Client ID from IRS IRIS.

The entire process to integrate PeopleSoft with the IRS IRIS A2A service is documented in the technical brief Generate JSON Web Key or JSON Web Key Set for IRS Connection. This documentation covers the first portion of this process.

Prerequisites

Ensure that Integration Broker is configured. This functionality works in conjunction with Integration Broker REST services.

See Understanding the Integration Broker Configuration Activity Guide.

The web server administrator should be familiar with how to set up the web site securely, including how to request and install the keystore and digital certificates for the PeopleSoft environment.

See Installing Web Server-Based Digital Certificates.

Creating a Key with pskeymanager

Use the pskeymanager utility to generate a key and an encrypted password, which you will use to generate a JSON Web Key, or JWK.

See Understanding the PSKeyManager Utility

In a command prompt, change to the following directory.
For <PS_CFG_HOME>, specify the location of your configuration home, which hosts your web server configuration. For <domain_name>. specify the name of the installed PeopleSoft Pure Internet Architecture domain for which you want to obtain encryption keys.

<PS_CFG_HOME>\webserv\<domain_name>\piabin
Enter the following command:
```
pskeymanager -create
```
Follow the prompts and enter the requested information to create a new private key and a CSR for your web server.
- Pskeymanager uses the keystore in <PS_CFG_HOME>\webserv\<domain_name>\piaconfig\keystore\pskey.
- Pskeymanager prompts you for an alias for the new keys. This is the name you’ll use to refer to the keys in the next section.
- Pskeymanager prompts you for a Subject Alternate Name (SAN). Enter one or more domain name server (DNS), IP address, EMAIL, URI, or an arbitrary object identifier (OID) in the format type:value.
- Pskeymanager prompts you for distinguished name fields. Enter the appropriate values for your organization.
- Pskeymanager prompts you for information about the CSR expiration date, key size, key algorithms, and the private key password. All of these fields have default values.
- Pskeymanager makes a backup copy of an existing pskey file.
- Pskeymanager creates the private key inside the keystore, and creates the CSR as a file called ServerABC_certreq.txt in the current directory. You use the CSR to obtain your signed public key certificate and a root certificate from a CA.
Use the PSCipher Java utility to encrypt the private key password.
1. Change directory to <PS_CFG_HOME>\webserv\<domain_name>\piabin and run the command.
  Microsoft Windows: pscipher.bat mypassword
  
  Linux: ./PSCipher.sh mypassword
2. Save the encrypted value.
  See Encrypting Passwords Using the PSCipher Java Utility
Make a note of the JWK alias and encrypted password for use in the next section.

Configuring the Integration Broker Properties File

Reference the alias you generated with pskeymanager in the integration.proeprteies file.

Locate the integration.properties file and open it for editing.
The default location for the file is: <PS_CFG_HOME>\webserv\<domain_name>\applications\peoplesoft\PSIGW.war\WEB-INF.

Specify the JWK alias and the encrypted private key password from the previous section.

The private key password is typically the same as the PeopleTools keystore password

# OAuth2 Client used for creating JWT-Bearer during Assertion Grant Type in HttpTargetConnector 
ig.AssertionKeyAlias=<JWK alias>
ig.AssertionKeyPassword={V2.1}xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Specify the full path to the PeopleTools keystore, pskey, and the encrypted password.

secureFileKeystorePath=<PS_CFG_HOME>/webserv/peoplesoft/piaconfig/keystore/pskey
secureFileKeystorePasswd={V2.1}xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Running the Script to Generate JWK

Export the JWK you generated as a JSON file to submit to the IRIS A2A service.

In a command prompt, change to the following directory:
<PS_CFG_HOME>\webserv\<domain_name>\piabin
Run the script to generate a JSON web key file.
Microsoft Windows: PSJWKExport.bat

Linux: ./PSJWKExport.sh
The script generates a new file, jwks.json, in the following location:
<PS_CFG_HOME>\webserv\<domain_name>\applications\peoplesoft\PSIGW.war\psjwk\jwks.json

4. If there is an existing file in the same directory, it will be renamed to jwks-XXXX-XX-XX.json.
You can access the file by entering one of the following URIs in a browser:
https://<host_name>[:<ssl-port>]/PSIGW/psjwk/

OR

https://<host_name>[:<ssl-port>]/PSIGW/psjwk/jwks.json

Note:
The only allowed URL protocol is HTTPS with GET option. If you enter an HTTP port, it will be converted to HTTPS.

Registering the JWK with IRIS and Configuring the OAuth Custom Service

After you generate the JWK, you must complete additional steps before you can use the IRS Information Returns Intake System (IRIS) Application to Application (A2A) service, as documented in the technical brief Generate JSON Web Key or JSON Web Key Set for IRS Connection.