Use a server key with the OpenEdge Authentication Gateway

Create a server key on the Authentication Gateway Server

Enable the oests.server domain

In following steps, you will enable a new domain by editing the existing oests.server entry:

1. Enable the oests.server domain by completing the following steps:
   1. Make a copy of the original C:\OpenEdge\WRK\oeauthserver\webapps\ROOT\WEBINF\config\domains.json file, and name it domainsORIG.json, in case you want to revert to the original json at any point.
   2. In a text editor, open the C:\OpenEdge\WRK\oeauthserver\webapps\ROOT\WEBINF\config\domains.json file. Open the file and search for "name" : "oests.server".
   3. Set the oests.server domain's “enabled” to true, as shown here:

      

      Note: The other options required but already set by default are the sso "enabled" : "true" and "authProvider" : "anonymous". Do not change the authProvider. It must be anonymous to work.
   4. Save domains.json. We did not modify the name of this JSON file because it referenced in the sts.properties which is used by the Authentication Gateway to customize its properties.
      Note: If you are worried that you may have made an edit to the JSON file that corrupted the file, you can use an online JSON editor to check that your JSON is valid.
2. Add the domain and password to the keystore configuration file:
   1. On your Authentication Gateway server instance, open the oeauthserver/webapps/ROOT/WEB-INF/config/domainsks.csv file
   2. Edit the file to replace changeme! with passwordkey that you just created as the server key access code for the domain, for example:

      

      Note: Encode the password used in mydomainsks.csv file using the genpassword utility. See genpassword for an example for creating an encoded password.
      Note: The line in the mydomainsks.csv file with only a comma (,) is a blank domain with a blank domain access code. The blank domain is pre-defined in the domains.json file with the entry "name" : "" and "authProvider" : "properties".
   3. Save the file as mydomainsks.csv. Using a custom name allows you to create .csv files specific to your environment.
3. Generate the keystore for the Authentication Gateway server:
   1. In a Proenv command prompt, change to the config directory.

      proenv>cd C:\OpenEdge\WRK\oeauthserver\webapps\ROOT\WEB-INF\config

   2. Run the following command to create an encrypted keystore called domains.keystore:

      proenv>gendomreg mydomainsks.csv domains.keystore

      

      The output of the gendomreg utility is the domains.keystore file.

      The .csv file is used to create an association between the oests.server domain in the domains.json and the domain access code. This domain access code is a secret that both the Authentication Gateway server and the client OpenEdge database know, which is used to verify client-principal authenticity.

      The .csv file contains all of the OpenEdge Domain names and their domain access code that the Authentication Gateway server is permitted to work with. The .csv file is compiled into an encrypted domains.keystore file for security purposes. This encrypted keystore file is what would be deployed into an ITOps server. The .csv file with clear-text OpenEdge Domain access codes would not be deployed to an ITOps server, but retained for restricted access by ITOps administrators. When the Authentication Gateway server receives a client-principal of an individual who is asking for it to do something, the Gateway server looks in the domains.keystore file to find the OpenEdge Domain specified in the client-principal. If it is found, then the Gateway server uses the OpenEdge Domain's access code to validate the client-principal before it is accepted and used.

      The mydomainsks.csv file should be moved somewhere safe and not kept with either the Authentication Gateway server or the database because it contains clear text password information.

4. Edit the sts.properties file to enforce the use of the keystore:
   1. Make a copy of the C:\OpenEdge\WRK\oeauthserver\webapps\ROOT\WEB-INF\config\sts.properties named sts.ORIG.properties in case you want to go back to the original settings.
   2. Open the sts.properties file in a text editor.
   3. Enable the use of server keys by setting sts.server.key.enabled to true:

      # Optional: Enable client/server access key validation for clients of the # STS application. Set this to true to require the use of the server key # file configuration and validation of STS client acess-keys. # # Set this property to true to authenticate individual OE installation's # access to use the STS application and block fake/rouge clients. # # Defaults to false. sts.server.key.enabled=true

   4. Specify where to find the key file by setting sts.server.keyfile to the key file path that was set earlier in the oeauthserver/conf directory, for example:

      # Optional: STS server key file location. This propery is required if the # sts.server.key.enabled property is set to 'true'. # # Default name is oests-key.ecp. Specific full file-system path to file # to ensure it can be found properly. # # Use the bin/stskeyutil utility to generate this encrypted Server access key # file, which will be used to generate and install the STS applicaiton client's # access-keys. Must be specified if sts.server.key.enabled=true # # ( make sure to use forward slashes in file paths and URLs, even on windows ) sts.server.keyfile=C:/OpenEdge/WRK/oeauthserver/conf/oests-key.ecp

      Note: You must use forward slashes even on Windows when specifying the path name.
   5. Provide the Authentication Gateway server's key file password by setting the sts.server.keyfilepassword property to the password that was specified at server key creation, for example:

      # sts key file password. Must be provided if server key file is specified in # sts.server.key.enabled=true . # May be encoded using genpassword. Make sure to include the codec prefix. sts.server.passwordencoder=ae2h4 sts.server.keyfilepassword=ae2h4::a9cf56a1565721ce9a0628cd1297f8d01b5290ea2b2d5585974 c7589eb07415d75906cc1ca9f4f53b05bce76b3a2756a

      Note: The sts.server.keyfilepassword password used for server key file in the example above is the same encoded password created in Step 2, using the genpassword utility. See genpassword for an example for creating an encoded password.
      Note: In a production environment, use a stronger password to seal with key file. In a later topic, this tutorial explains how to Use encoded passwords in the sts.properties file.
   6. Save the file.
5. Restart the Authentication Gateway server. The sts.properties changes are not actively monitored for updates, so a restart of the server is required to pick up changes to this properties file.
   1. Change to the Gateway server directory, for example:

      proenv>cd C:\OpenEdge\WRK\oeauthserver

   2. Run tcman pasoestart -restart to stop the server, clean the log files, and then restart the server:

      proenv>bin\tcman pasoestart -restart

      Using tcman pasoestart -restart shows the running processes in the Exit processes line. The multiple exit processes indicate the server and security token service are running, for example:

      Stop running PASOE instance oeauthserver . Restarting the running PASOE instance oeauthserver .............. Start action: restart Initial state: started Initial processes: 9008 5208 6244 Exit state: started Exit description: Restarting the running PASOE instance oeauthserver Exit processes: 8424 2564 6320 Exit status: 0 Exit errors:

Install the server key on the OpenEdge database machine

In a distributed system, you need to copy the Authentication Gateway server key (oests-key.ecp) to the OpenEdge Database machine that acts as a client to the Authentication Gateway server.

Install the key on the multiple distributed client machines

If you are running on a distributed system with more than two machines, repeat the "Install the server key on the client OpenEdge database machine" steps on each client machine where you want to secure your database with the Authentication Gateway. Then, test each client machine with the following procedure.

Test the client connections with a client key

Summary

In this topic, you created a server key using the stskeyutil utility. Using the domains.json file, you configured the oests.server domain to require a server key. You created a custom mydomainsks.csv file to create your server key and put it in the keystore using thegendomreg utility. Then, by modifying sts.properties file, you made that instance require the key and specified the key file location and password, and then restarted the server to reload the properties. You also installed the key using the stskeyutil tool, then tested access with the key. Optionally, we encouraged you to test removing the client key, noting that the message of a missing key is purposefully vague to be resolved by a database administrator. The client key must be kept in the %DLC%\keys directory of each client machine that uses the Authentication Gateway for authentication.