Use a named domain for authentication

This topic provides an introduction to using domains with the Authentication Gateway and database. This topic describes how to enable a domain that uses local operating system credentials to manage access to the Authentication Gateway server and database.

Domains exist in two places, the OpenEdge Authentication Gateway Server’s Security Token Service configured with the domains.json file, and in the OpenEdge database. Up until now, you have been using the blank domain shipped in the domains.json file, and a pre-existing blank domain in the sports2020 database. In this topic, we add a domain called local to the domains.json file, and authenticate to the database using the operating system credentials of the Authentication Gateway server machine.

In this topic, we will complete the following steps:

1. Shut down and disable the use of the Authentication Gateway
2. Create a security safety net
3. Add a local domain
4. Add named security administrators
5. Add the local domain to the domains.json file
6. Restart the Authentication Gateway server
7. Enable the use of the Authentication Gateway on the database
8. Test database connection

Shut down and disable the use of the Authentication Gateway for the database machine

Create a security safety net

In a production environment, you would want to have multiple security administrators. For the purposes of the tutorial we have only added a single user.

Add a local domain to the database

In this task, you will connect to the sports2020 database using the Data Administration tool on your database machine. We will add a domain that allows you to use the operating system login credential to connect to the database.

1. In the Progress Database window, press F3 > A (Admin) > S (Security) > M (Domain Maintenance) > D (Domains).

   

2. Tab to < Create > and press Enter.
3. Enter the following information
   1. Name: local
   2. System Type: _oslocal
      Note: To access the drop-down menu that specifies the System Type options, tab to the System Type field and press the down arrow key.
   3. Access code: localkey
      Note: The access code appears as blank. It must be the same as the access code you defined for the local domain in the domainsks.csv file.
   4. Description: local domain

      

4. Select < Save > to save the changes.
5. Select < Done >.

   

6. Select < Done >.
7. (Optional) You can use the Data Administration Tool to dump the newly created records to a file on your local machine. Press A (Admin) > D (Dump Data and Definitions) > Y (Security Domains). If you specify no output directory, the files will be generated in the C:\OpenEdge\WRK\db directory that you launched the Progress window from.

   For your benefit, we have included a screen capture of the output. You can see the domain access code was encrypted. In this case, it is stored as combination of numbers and letters.

   

You are now ready to configure the OpenEdge Authentication Gateway server’s STS to use the newly added domain.

Adding named security administrators inside the database

In these steps, you will create a list of users who will have permission to perform security administrator duties like add new Security administrators. We will add the myAdmin user with the domain mySecurityDomain to avoid locking ourselves out of the database.

Additionally, we’ll add the administrator user on the Authentication Gateway server. We’ll add two ways to refer to the user. The first, administrator@local, references the local domain. The second, administrator, using a blank domain.

1. On the database machine's Data Dictionary, select A (Admin) > S (Security) > A (Security Administrators) and add your security admin (myAdmin) to the list.
2. Delete the asterisk (*), which made everyone a security administrator.

   

3. Edit the list to explicitly name the following users:

   myAdmin,myAdmin@mySecurityDomain,administrator administrator@local

   There cannot be spaces between Security Administrators users, but you can have a linebreak to ensure the user entries display on the screen.
   Note: You may need to enter your operating system username for your database machine as an administrator to the list. For example, if your local operating system login on the database machine is hsimpson, you would need to add hsimpson to the list of Security Administrators as well.
4. Press F1 to save.
5. Select <Yes> to make the change.

   

   Note: Adding myAdmin is for testing purposes only. In a production deployment environment, you would want tight control over who can change security.

Add the local domain to domains.json

In this section, you modify the domains.json file to add a local domain on your Authentication Gateway server.

1. On the Authentication Gateway server, open the C:\OpenEdge\WRK\oeauthserver\webapps\ROOT\WEB-INF\config\domains.json file in a text editor.
2. Copy the contents of the blank ("name" : "") domain definition, and paste them above or below the original blank domain, so that you have two blank domains in the domains.json file.
3. Update the one of the blank domains with the following edits:
   1. Name: local
   2. Description: Local domain for OS credentials
   3. AuthProvider: _oslocal
   4. Groups: { }

      

      Note: There are multiple ways to authenticate through _oslocal. For more information about using _oslocal on Unix-like platforms, see the following Knowledge Base article: OpenEdge authentication gateway(OEAG) fails to authenticate through _oslocal if user account is stored locally in /etc/passwd. If you follow the Knowledge Base article and provide local authentication using stsclientutil -cmd exchange requires an additional change to the domains.json file:

      "exchange":{ "enabled":true, "options":"-processid" },

4. Save the changes.
5. Open the mydomainsks.csv file.
6. Underneath the blank domain (indicated with a comma), enter a line for local,localkey:

   

   Also, confirm that the oests.server,passwordkey is correct.

7. Save the changes.
8. Change directory to C:\OpenEdge\WRK\oeauthserver\webapps\ROOT\WEB-INF\config:

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

9. Run the following command to combine the key and the domain and password files into the required domains.keystore:

   proenv>gendomreg mydomainsks.csv domains.keystore

   

   Note: In production environments, you would remove the domainsks.csv file and save it somewhere secure since it can be used to generate the domains.keystore file.
10. Stop, clean, and restart the server to apply the changes:

    proenv>cd C:\OpenEdge\WRK\oeauthserver\bin proenv>tcman pasoestart -restart

11. From your client database machine, test the security token service to verify it will authenticate the user on your machine:

    proenv>stsclientutil -url https://yourgatewayhostname:8443 -nohostverify -cmd authenticate -user yourOScredentials@local Enter user's password:

    For yourOScredentials, enter your operating system login for the Authentication Gateway server machine, and then the password that you use to access the Authentication Gateway machine.
12. You will see the following message if configured correctly:

    Authentication succeeded

13. Test authentication using the blank domain (such as using the test user from the users.properties file as from earlier):

    proenv>stsclientutil -url https://yourgatewayhostname:8443 -nohostverify -cmd authenticate -user test -password test

(Optional) Disable the default blank domain

Disabling the blank domain consolidates the user credentials to use only the local operating system credentials. For testing, however, you can choose not to disable the blank domain. To re-enable the blank domain, simply uncomment the blank domain entry into mydomainsks.csv (a line with a comma), and use gendomreg to re-generate a domains.keystore file. In a production environment, keep your domain registry filemydomainsks.csv in a secure location.

Enable the Authentication Gateway on the database

Next, restart the database server and enable the authentication gateway as the enforcer of security:

1. On the database machine, change to the database directory, for example:

   proenv>cd %WRKDIR%\db

2. Ensure your database is not running:

   proenv>proshut sports2020 -by

3. Update the stsurlutil by connecting with -1 to connect to the database using the security administrator and password:

   proenv>stsurlutil update -url https://yourgatewayhostname:8443 -ssl -nohostverify -db sports2020 -1 -U myAdmin@mySecurityDomain -P myAdmin [2020-08-03T22:32:21.810-04:00] DBSTSURL INFO OPERATION: UPDATE [2020-08-03T22:32:21.811-04:00] DBSTSURL INFO SESSION:PARAM: URL:https://yourgatewayhostname:8443,SSL-OPTIONS:-nohostverify [2020-08-03T22:32:21.811-04:00] DBSTSURL INFO URL: https://yourgatewayhostname:8443 [2020-08-03T22:32:21.811-04:00] DBSTSURL INFO TEST-URL? yes [2020-08-03T22:32:21.811-04:00] DBSTSURL INFO SSL-OPTIONS: -nohostverify [2020-08-03T22:32:21.812-04:00] DBSTSURL INFO SERVERNAME: [2020-08-03T22:32:21.911-04:00] DBSTSURL INFO STS Url created for "sports2020" [2020-08-03T22:32:21.911-04:00] DBSTSURL INFO OPERATION COMPLETE

4. Enable the Authentication Gateway on the database using proutil:

   proenv>proutil sports2020 -C enableauthgateway -U myAdmin@mySecurityDomain -P myAdmin OpenEdge Release 12.2 as of Tue Mar 17 19:02:26 EDT 2020 Warning: It is recommended that connection role security enforcement be configured when using the OpenEdge Authentication Gateway. (18519) Authentication Gateway has been enabled for database sports2020. (12479)

5. Start the database server with the -nohostverify option:

   proenv>proserve sports2020 -nohostverify OpenEdge Release 12.2 as of Tue Mar 17 19:02:26 EDT 2020 22:33:51 BROKER This broker will terminate when session ends. (5405) 22:33:51 BROKER The startup of this database requires 40Mb of shared memory. Maximum segment size is 1024Mb. 22:33:51 BROKER 0: Multi-user session begin. (333) 22:33:51 BROKER 0: Before Image Log Initialization at block 5 offset 332. (15321) 22:33:51 BROKER 0: Login by Administrator on CON:. (452)

Test the connection to the database

Now that you have added user to the database, added a domain to the database and updated the domains.json and domains.keystore to hold the new local domain for the Authentication Gateway’s Security Token Service you are ready to test the database connectivity.

1. On the database machine, change to the db directory if you are not already there, for example:

   proenv>cd %WRKDIR%\db

2. Login using the credentials you provided earlier:

   proenv>mpro sports2020 -U yourOScredentials@local -P yourOSpassword

3. After login, you are in a Progress editor and connected to the database, where you can run the code to display database records, such as using the following example code:

   FOR EACH Customer: DISPLAY Name. DISPLAY CustNum. END.

4. Press F1 to compile and run the code. It produces an output like the following:

   

5. Press ESC to stop the program.
6. Exit the procedure editor without saving.
7. Test the negative case by trying to connect as an intruder or with the wrong password:

   proenv>mpro sports2020 -U intruder@local -P "intruder"

   This produces the error: "Your Password and Userid intruder do not match".

   Note: If you kept the blank domain active, you would also be able to access the sports2020 database with the test user and password with a blank domain, for example:

   proenv>mpro sports2020 -U test -P test

8. To prove that all logins are handled by the Authentication Gateway, try to log in to your database as the Security Administrator that defined inside your database:

   proenv>mpro sports2020 -U myAdmin@mySecurityDomain -P myAdmin

   The reason this authentication request fails is because the domain mySecurityDomain and user myAdmin have only been defined on the database. If you defined a new domain and user on the Authentication Gateway server, and then added the domain to the domains.json and domainsks.csv file that you use to compile your domains.keystore, then you would be able to access your database using these credentials.

Summary

In this topic, we first shut down and disabled the use of the Authentication Gateway on the database. Then we created a security safety net in our database in the form of the myAdmin@mySecurityDomain administrative user, which can be used to access the database whenever the Authentication Gateway is disabled. Then we added a local (_oslocal) domain to the database using the Database Administrative Tools. In the database, we also defined the security administrative users. Then we added the local domain to the domains.json file, and updated the domain registry (mydomainsks.cvs and domains.keystore files). We added and removed domains (such as the blank domain) to the mydomainsks.cvs and regenerated the domains.keystore based on domain needs. Then we re-configured out database to use the Authentication Gateway for authentication, and tested the database connection with the local user, which uses the operating system login and password to the Authentication Gateway machine for authentication.