This topic describes enabling the OpenEdge database to use the Authentication Gateway to secure client connections.

Enabling a database to use the Authentication Gateway requires several steps:
  1. Create a copy of the sports2020 database.
  2. Add the Authentication Gateway URL to the database.
  3. Enable the database to use the Authentication Gateway.
  4. Test a client connection.
Note: You can use the Progress Developer Studio for OpenEdge to access a GUI client and Database tools. Since much of the configuration of the Authentication Gateway is done on the command line, it was faster to test the connectivity with the mpro utility and accessing the character based Data Dictionary. Feel free to access the ABL client or Database activity using the graphical tools if you prefer.

Create a copy of the sports2020 database

For the purposes of this tutorial, we will create the sample sports2020 database in the working directory of our OpenEdge instance. This should be done on a separate machine from your Authentication Gateway server, so there is a separation between the Authentication Gateway server and the OpenEdge database machine.
  1. On the database machine, use Proenv to navigate to the OpenEdge WRK directory, for example:
    proenv>cd %WRKDIR%
proenv>cd
C:\OpenEdge\WRK
  2. Make a new directory to separate the database, for example:
    proenv>mkdir db
  3. Navigate into this new db directory:
    proenv>cd db
  4. Create a copy of the sports2020 database in this location:
    proenv>prodb sports2020 sports2020
Procopy session begin for Administrator on CON:. (451)
Database copied from C:\Progress\OpenEdge\sports2020. (1365)
Procopy session end. (334)
    Note: If you created this database as an administrator, you may need to remove the read-only restriction on the db directory. To remove this restriction on Windows:
    1. Open the Windows File Explorer and navigate to the WRK directory.
    2. Right-click the db directory and select Properties.
    3. Uncheck the Read-only attribute.
    4. Click Apply.
    5. Select Apply changes to folder, subfolder, and files.
    6. Click Ok.

Add the Authentication Gateway URL to the database

Note: Before making any security changes to your database environment, it is a standard practice for database administrators to make a backup of their database. Ensure you have a current and tested backup of your database before proceeding with the next steps.
To add the Authentication Gateway server URL to enable Gateway authentication on your database:
  1. The Authentication Gateway server must be running to register the URL for the Authentication Gateway server with the database. On the Authentication Gateway machine, ensure the instance is running:
    proenv>cd %WRKDIR%\oeauthserver
proenv>bin\tcman pasoestart -restart

    When the startup completes with a zero-errors exit code, you can switch over to the database machine to add the Authentication Gateway URL to the database.

  2. On the database machine, ensure you are operating in the directory that hosts the sports2020 database, for example:
    proenv>cd C:\OpenEdge\WRK\db
  3. The database cannot be running when you register the URL for the Authentication Gateway server with the database. Ensure the database is not running with the proshut command, for example:
    proenv>proshut sports2020 -by
OpenEdge Release 12.2 as of Tue Mar 17 19:02:26 EDT 2020
There is no server for database sports2020. (1423)
  4. Run the following command to register the URL for the Authentication Gateway server with the database. The Authentication Gateway server must be running for the URL to be verified by the utility. Additionally, the database server must be shut down to use this command with the -1 option:
    proenv>stsurlutil update -url https://yourgatewayhostname:8443 -ssl -nohostverify -db sports2020 -1
[2020-07-19T21:06:56.846-04:00] DBSTSURL INFO OPERATION: UPDATE
[2020-07-19T21:06:56.846-04:00] DBSTSURL INFO SESSION:PARAM: URL:https://yourgatewayhostname:8443,SSL-OPTIONS:-nohostverify
[2020-07-19T21:06:56.847-04:00] DBSTSURL INFO URL: https://yourgatewayhostname:8443
[2020-07-19T21:06:56.847-04:00] DBSTSURL INFO TEST-URL? yes
[2020-07-19T21:06:56.847-04:00] DBSTSURL INFO SSL-OPTIONS: -nohostverify
[2020-07-19T21:06:56.847-04:00] DBSTSURL INFO SERVERNAME:
[2020-07-19T21:06:56.954-04:00] DBSTSURL INFO STS Url created for "sports2020"
[2020-07-19T21:06:56.954-04:00] DBSTSURL INFO OPERATION COMPLETE

    This command loads the URL of the Authentication Gateway Server’s Security Token Service (STS) into the database with the STS URL Utility. This command requires connecting to the database. In this example, we set the value with a single user mode connection (-1). Until we add certificates, we continue to use the -ssl -nohostverify option.

Enable the database to use the Authentication Gateway

With the blank domain as the default domain installed by the Authentication Gateway and the URL added, you are now ready to enable the use of the Authentication Gateway to enforce database security.

  1. Ensure that you are operating in your database server directory, for example:
    proenv>cd C:\OpenEdge\WRK\db
  2. Run the following command to enable the Authentication Gateway server to secure your database:
    proenv>proutil sports2020 –C enableauthgateway
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)
    Note: The database server cannot be running when you enable the Authentication Gateway.

    This command enables the Security Token Service for your database. All database connections must now go through the Security Token Service to authenticate credentials before accessing your database. Additionally, you can add connection role security to limit access through authorization roles. This will be addressed in later topics.

  3. Start the database server using the –nohostverify option, since the database is still using the sample certificates:
    proenv>proserve sports2020 –nohostverify
OpenEdge Release 12.2 as of Tue Mar 17 19:02:26 EDT 2020
21:25:00 BROKER     This broker will terminate when session ends. (5405)
21:25:00 BROKER     The startup of this database requires 40Mb of shared memory.  Maximum segment size is 1024Mb.
21:25:00 BROKER  0: Multi-user session begin. (333)
21:25:00 BROKER  0: Before Image Log Initialization at block 0  offset 1519. (15321)
21:25:00 BROKER  0: Login by administrator on CON:. (452)

Test an ABL connection

The database is now ready to use the Authentication Gateway server's Security Token Service to authenticate, so let's test it using an ABL client.

  1. With the database server running in multi-user mode, attempt to start a client session without supplying a correct user name and password:
    proenv>mpro sports2020 -U intruder -P intruder
    This produces the following error message:
  2. Attempt to start a client session with a valid user name and password:
    proenv>mpro sports2020 -U test -P test
    Instead of an error message, you enter a procedure editor like the following:
  3. To exit the procedure editor, press F3 to access the Menu, F to select File, and then X to exit.

Summary

In this topic, you created a database from the sample OpenEdge sports2020 database, added the URL for the Security Token Service, and effectively locked the database to outside access by forcing all connections to the database to go through the Security Token Service. This topic introduced the Authentication Gateway utility stsurlutil to specify that the database uses a specific URL for all connections to authenticate the database users. Then, we used the database utility proutil –C enableauthgateway to turn on the Gateway authentication. This topic also shows the importance of testing both the success and failure cases for connecting. The test user was again authenticated using the users.properties file on the Authentication Gateway server.