Replace the default key and certificate on OpenEdge Authentication Gateway server

The OpenEdge Authentication Gateway server is accessed by encrypted HTTPS calls. To learn the basic setup and review the configuration of the server, we have been suppressing the error messages with the -nohostverify options on the server and test utilities.

To fully implement an OpenEdge Authentication Gateway Server, the server must always require a valid certificate. In this topic, we implement a self-signed certificate for our server, and copy it to the client machines that access the Authentication Gateway server.

In a production environment, you would need to submit a public key to a Certificate Authority (CA) to request a server certificate, and then copy the root and server certificate to your Authentication Gateway server and client machines. To request a certificate, you would first create a Key Pair, which is a private key keystore (a.pk1 file) and public key (a .pk10 file), and then submit the .pk10 file to the CA.

For more information about this process, see Obtain a certificate from a certificate authority in Manage PAS for OpenEdge. This activity is out of the scope for this tutorial.

This topic covers the following steps:

  1. Create a self-signed certificate on the Authentication Gateway server
  2. Import the certificate on the Authentication Gateway server
  3. Copy certificate to the client machine (or machines)
  4. Configure the Authentication Gateway server to use the keystore repository
  5. Test the connections

Create a self-signed certificate on the Authentication Gateway server

To create a self-signed SSL certificate with OpenEdge for use with Authentication Gateway clients:
  1. In Proenv on the Authentication Gateway server, navigate to the oeauthserver\conf directory
  2. Rename the original tomcat-keystore.p12 file to tomcat-keystore.p12.orig in case you want to revert to the default keystore:
    proenv>rename tomcat-keystore.p12 tomcat-keystore.p12.orig
    Note: In this case, we are simply renaming the original tomcat-keystore.p12 file, rather than creating a backup copy of the file. This is because the next steps would add an additional entry to the existing tomcat-keystore.p12 file if the tomcat-keystore.p12 file were present in the oeauthserver\conf directory.
  3. Use the keytool utility to generate a key pair keystore file called tomcat-keystore.p12:
    proenv>keytool -genkeypair -keyalg RSA -alias oeAuth -keystore tomcat-keystore.p12 -storetype pkcs12 -validity 100 -keysize 2048 -dname "CN=gatewayhostname,OU=Training,O=Progress,L=Bedford,ST=Massachusetts,C=US"

    For the -dname option, provide the Authentication Gateway hostname as the CN, and then fill in the rest of the Domain Name with attributes that best suit your organization. This command produces the tomcat-keystore.p12 in the oeauthserver\conf directory.

    Provide a password for the keystore, in this example you can use password with the usual caveats.

  4. (Optional) Verify the contents of the keystore using the password you created in the last step:
    proenv>keytool -list -v -keystore tomcat-keystore.p12 -storetype pkcs12
Enter keystore password:
    Review the output, which contains the one oeauth alias and additional information about the keystore, as seen in the following screen capture:
    media/image56.png
  5. Export the certificate as a file called selfsigned.cer using the keystore password you created in a previous step:
    proenv>keytool -exportcert -rfc -alias oeAuth -keystore tomcat-keystore.p12 -file selfsigned.cer
Enter keystore password:
Certificate stored in file <selfsigned.cer>
    This certificate is also created in the oeauthserver\conf directory.

Import the certificate into the Authentication Gateway server

Use the certutil command to make certificate files in the certs directory. These files are used by clients who require the necessary keys when connecting.

  1. On the Authentication Gateway machine, run the certutil -import command to import the selfsigned.cer and create a certificate store entry with a generated alias name in the %DLC%\certs directory: 
    proenv>certutil -import selfsigned.cer
Importing trusted certificate to alias name: dd5d2225

    The certificate alias name will likely be different on your system.

  2. Verify that the certutil -import command created a file with the extension .0 in the %DLC%\certs directory. In this example, the file would be called dd5d2225.0.

Copy the certificates to the client machine (or machines)

Every client (database or stsclientutil user) that will connect to the Authentication Gateway server needs a copy of the certificates that were generated by the certutil -import commands.

  1. Copy the newly-created .0 file in the %DLC%\certs directory of the Authentication Gateway server to the %DLC%\certs directory of each OpenEdge client that will authenticate against the Authentication Gateway.

    In the above example, the certutil -import generated a server certificate named dd5d2225.0 in the %DLC%\certs directory of the Authentication Gateway server. Copy this file to your client database machine into the %DLC%\certs directory. Repeat this process for each client machine that uses the Authentication Gateway, if you have multiple machines set up.

Configuring the Authentication Gateway server to use the keystore

If you used a new keypass or keyalias you will need to update the catalina.properties file, so that your Authentication Gateway server will have the correct keypass and keyalias to use the updated keystore.

  1. On the Authentication Gateway server machine, open the C:\OpenEdge\WRK\oeauthserver\conf\catalina.properties file in a text editor.
  2. Search for the # JSSE keystore section.
    media/image57.png
  3. Edit the keypass and key alias to match your system. You are replacing the alias for the default certificate that is shipped with OpenEdge. This example uses the values created for this exercise. In a production system you would be customizing this like all other passwords and replacement files. Note that the sslc utility lowercased the alias name in the Tomcat keystore, if you do not match what was shown in the listing (lowercased oeauth) you will fail to connect.
    • psc.as.https.keypass=password
    • psc.as.https.keyalias=oeauth
  4. Save and close the file.

Test the connection

In this section, you will restart the server to get the appropriate credentials from the keystore to be able to participate in secured communication. The result is that you will be able to connect without using the -nohostverify option, because all participants have the appropriate keystores and certificate for communicating.

  1. Stop, clean and restart the Authentication Gateway server from the oeauthserver directory:
    proenv>cd %WRKDIR%\oeauthserver
proenv>bin\tcman pasoestart -restart
  2. On your client machine, use stsclientutil to ping the Security Token Service for authentication. Be sure to replace yourgatewayhostname in the following command. This time you will not need the -nohostverify option because you have a valid certificate. 
    proenv>stsclientutil -url https://yourgatewayhostname:8443 -cmd ping
ping ... OK
  3. On your client machine, use stsclientutil to pass a set of credentials to the Authentication Gateway for authentication. Be sure to replace yourgatewayhostname in the following command. Again, these client calls to the Authentication Gateway server no longer need the -nohostverify option.
    proenv>stsclientutil -url https://yourgatewayhostname:8443 -cmd authenticate -user testuser1@local -password testuser1
Authentication Succeeded

proenv>stsclientutil -url https://yourgatewayhostname:8443 -cmd authenticate -user test -password test
Authentication Succeeded
    Note: Ensure you have the correct domains enabled on your Authentication Gateway to test your authentication with the test user. In order for the test user and password to be authenticated, the blank domain must still be enabled on the Authentication Gateway server. If you have replaced the blank domain with a local domain, as in the Use a named domain for authentication exercise, you can only test the authentication with the local OS credentials (such as the testuser1@local that you added to your Authentication Gateway server, or yourOScredential@local and yourOSpassword) for your Authentication Gateway server.
  4. Test an authentication attempt with a invalid user, for example:
    proenv>stsclientutil -url https://yourgatewayhostname:8443 -cmd authenticate -user intruder -password intruder
    media/image61.png
  5. On the client machine, stop the database:
    proenv>cd %WRKDIR%\db

proenv>proshut sports2020 -by
OpenEdge Release 12.2 as of Tue Mar 17 19:02:26 EDT 2020
Shutdown is executing. (1613)
Shutdown complete. (1614)
  6. Restart the database without -nohostverify:
    proenv>proserve sports2020
OpenEdge Release 12.2 as of Tue Mar 17 19:02:26 EDT 2020
15:07:30 BROKER     This broker will terminate when session ends. (5405)
15:07:30 BROKER     The startup of this database requires 40Mb of shared memory.  Maximum segment size is 1024Mb.
15:07:30 BROKER  0: Multi-user session begin. (333)
15:07:30 BROKER  0: Before Image Log Initialization at block 5  offset 5143. (15321)
15:07:30 BROKER  0: Login by Administrator on CON:. (452)
  7. Test the database connection without using the -nohostverify option:
    proenv>mpro sports2020 -U adminOScredentials@local -P adminOSpassword

Summary

In this topic, you implemented certificates for the Authentication Gateway server and client OpenEdge database. You did all this so the HTTPS connections would work without the -nohostverify and the clients, server, and database could communicate using valid certificates encrypting the information passed over your connections.