This topic explains how to configure Dynamic Data Masking (DDM) on a database that is already enabled for OpenEdge Authentication Gateway (OEAG). It is a companion to Get started with DDM, adapted to reflect the differences that arise when user authentication is delegated to OEAG rather than managed in the _User table of the database.

Before you begin

Before you begin, ensure you have the following:
  • An understanding of how to set up OEAG, adding users, and configuring named domains on the Security Token Service (STS).

    For more details, see OpenEdge Authentication Gateway Tutorial.

  • A working OEAG instance with STS reachable at a known URL. For example:
    https://yourgatewayhostname:port
    Note: The default port is 8443, but if you specified a different port during the installation, be sure to make that change.
  • Two user accounts configured on the OEAG side that can be authenticated by the STS. This tutorial uses the OEAG properties authentication provider, so both AdminUser and GeneralUser example users are added to users.properties on the STS. For example,
    ...
AdminUser=AdminPass123,ROLE_PSCUser,enabled
GeneralUser=GeneralPass123,ROLE_PSCUser,enabled
    Verify both users can authenticate through the STS by running the following commands:
    proenv> stsclientutil -url https://yourgatewayhostname:port -cmd authenticate -user AdminUser@OEDomain -password AdminPass123 -nohostverify
    		 
    proenv> stsclientutil -url https://yourgatewayhostname:port -cmd authenticate -user GeneralUser@OEDomain -password GeneralPass123 -nohostverify
  • The sample mysports22 database with the Authentication Gateway enabled:
    proenv> proutil mysports22 -C enableauthgateway
    For more information, see PROUTIL ENABLEAUTHGATEWAY qualifier.
  • Ensure that a domain record exists in the target database. For example, if you are using the OEDomain domain, a corresponding domain record must be configured in mysports22. For creating and managing domains, navigate to Admin > Security > Domain Maintenance > Domains in the Data Administration tool. In a DDM-protected database, only the domain configuration is required. User accounts do not need to exist in the database because OEAG handles user authentication.
  • AdminUser@OEDomain registered as a security administrator on the target database. Because OEAG does not maintain database-level user records, you must add the fully-qualified identity, and not simply the username, by connecting to the target database as an existing security administrator, navigate to Admin > Security > Security Administrators in the Data Administration tool, and add AdminUser@OEDomain.
    Note: Specify the name in the fully qualified user@domain format and ensure that it matches the identity authenticated by OEAG. For example, AdminUser@OEDomain, not simply AdminUser.

Key differences from the base Get started with DDM topic

When authentication is delegated to OEAG, the following behaviors differ from the base Get Started with DDM topic:
Base Get started with DDM OEAG-enabled variant
Users are created through oDAS:CreateUser("AdminUser", ...) in a _User record No _User records are created. Users exist only in the OEAG identity store.
DDM role grants use oDAS:GetUser("AdminUser"):Name. The grantee is fetched from the _User record.

The grantee is set directly to the fully-qualified user@domain string. For example, oRole:Grantee = "AdminUser@OEDomain".

There is no _User record to look up because OEAG maintains user accounts in an external identity store. For example, the users.properties file of the STS, an LDAP directory, Microsoft Active Directory, an OpenEdge realm database, or the local users in the operating system, depending on the authProvider configured for the domain in domains.json.

Enable, configure, and activate DDM in an OEAG-enabled database

To enable, configure, and activate DDM in an OEAG-enabled database, complete the following steps:
Important: The example codes provided in the following steps work with OpenEdge Release 12.8.4 and later. They are not compatible with OpenEdge Releases 12.8 through 12.8.3.
  1. Copy the existing sample database to a new database. For example, copy the Sports2020 database into the mysports22 database.
    proenv>procopy $DLC/sports2020 mysports22
  2. Enable DDM for mysports22.
    proenv>proutil mysports22 -C enableddm
    Note: Enable the DDM feature before configuring and using it to check if the database is licensed for DDM.
    After you enable the database for DDM:
    • Clients earlier than OpenEdge 12.8 that are not aware of the DDM setup may not be able to open or connect to the database.
    • Activate DDM to configure it because DDM is inactive, by default.

    For more information, see PROUTIL ENABLEDDM qualifier.

  3. Start the database server for mysports22.
    proenv>proserve mysports22 -H localhost -S 5000
  4. Verify that both AdminUser@OEDomain and GeneralUser@OEDomain users can authenticate through the STS: 
    proenv> stsclientutil -url https://yourgatewayhostname:8443 -cmd authenticate -user AdminUser@OEDomain -password AdminPass123 -nohostverify
    		 
    proenv> stsclientutil -url https://yourgatewayhostname:8443 -cmd authenticate -user GeneralUser@OEDomain -password GeneralPass123 -nohostverify
    Both calls should return this output:
    Authentication succeeded
    Note: OpenEdge provides different ways to integrate with various user account systems, such as the built-in _oslocal authentication system for using Operating System (OS) local accounts, external user accounts accessed by an ABL authentication callback, and the OpenEdge Authentication Gateway. For more information, see Assert user identity.

  5. To determine user privileges for accessing the masked data, create a new role for database users (user-to-role mapping).

    The following example code creates the PAYROLL role, which regulates the privileges granted to users for data unmasking:

    USING OpenEdge.DataAdmin.*.

VAR DataAdminService oDAS. VAR IRole oRole.
VAR LOGICAL lResult.

ASSIGN oDAS = NEW DataAdminService(LDBNAME("DICTDB")).

oRole = oDAS:NewRole("Payroll"). 
oRole:Description = "Admin User Role".
// This role is used for Dynamic Data Masking
oRole:IsDDM = true.
lResult = oDAS:CreateRole(oRole). 

MESSAGE "Added Payroll Role".

DELETE OBJECT oDAS.
    1. Save the example code as addRole.p.
    2. Run addRole.p.
      proenv>mpro mysports22 -U AdminUser@OEDomain -P AdminPass123 addRole.p
  6. Create an authorization tag and associate it with the role you created in Step 4. An authorization tag establishes the connection between the user-defined DDM roles and the fields of a table to which a mask is to be applied.

    The following example code associates the #DDM_SEE_ContactInfo authorization tag with the PAYROLL role:

    USING OpenEdge.DataAdmin.*.

VAR DataAdminService service.
VAR IAuthTag oTag.
VAR LOGICAL lReturn.

ASSIGN service = new DataAdminService (LDBNAME("DICTDB")).

     oTag       = service:NewAuthTag("#DDM_SEE_ContactInfo"). 
     oTag:RoleName      = service:GetRole("Payroll"):Name.
     oTag:description = "Can see contact info".
     lRETURN = service:CreateAuthTag(oTag).

MESSAGE "Added Payroll to #DDM_SEE_ContactInfo".
QUIT.
    1. Save the example code as setAuthTagRole.p.
    2. Run setAuthTagRole.p.
      proenv>mpro mysports22 -U AdminUser@OEDomain -P AdminPass123 setAuthTagRole.p
    For more information on authorization tags, see Authorization tags.
  7. Grant user-defined roles to authorized users.

    The following example code grants the PAYROLL role to AdminUser: 

    USING OpenEdge.DataAdmin.*.
VAR DataAdminService oDAS.
VAR IGrantedRole     oRole.
VAR LOGICAL          lResult = FALSE.

ASSIGN oDAS = NEW DataAdminService(LDBNAME("DICTDB")).
oRole      = oDAS:NewGrantedRole().
oRole:Role = oDAS:GetRole("Payroll").

IF VALID-OBJECT(oRole:Role) THEN DO:
   // Grantee is the Client-Principal user returned by OEAG.
    // If the OEAG domain is set, use "AdminUser@<domain-name>".
  oRole:Grantee  = "AdminUser@OEDomain".
    oRole:CanGrant = FALSE.   // Cannot grant to others.
  // Granting the Payroll role to AdminUser
    lResult = oDAS:CreateGrantedRole(oRole).
END.
  8. Add a mask to the field to specify what a user sees if they are not authorized to view the unmasked data. The types of masks available are: default, literal, partial, and null.
    1. Default mask—To configure the default mask (prefix D:), the following example code uses the setDDMConfig() method and the #DDM_SEE_ContactInfo authorization tag for the state field of the Customer table. 
      USING OpenEdge.DataAdmin.DataAdminService FROM PROPATH.

DEFINE VARIABLE service AS DataAdminService NO-UNDO. 
DEFINE VARIABLE lResult AS LOGICAL NO-UNDO.

service = NEW DataAdminService(LDBNAME("DICTDB")).
lResult = service:setDDMConfig("customer","state","D:","#DDM_SEE_ContactInfo").

MESSAGE "Added Default mask".
QUIT.
      1. Save the example code as addDefaultMask.p.
      2. Run addDefaultMask.p.
        proenv>mpro mysports22 -U AdminUser@OEDomain -P AdminPass123 addDefaultMask.p
      For more information about default mask, see Default mask.
    2. Literal mask—To configure the literal mask (prefix L:), the following example code uses the setDDMConfig() method and the #DDM_SEE_ContactInfo authorization tag for the city field of the Customer table. 
      USING OpenEdge.DataAdmin.DataAdminService FROM PROPATH.

DEFINE VARIABLE service AS DataAdminService NO-UNDO. 
DEFINE VARIABLE lResult AS LOGICAL NO-UNDO.

service = NEW DataAdminService(LDBNAME("DICTDB")).
lResult = service:setDDMConfig("customer","city","L:MASKED","#DDM_SEE_ContactInfo").

MESSAGE "Added Literal mask".
QUIT.
      1. Save the example code as addLiteralMask.p.
      2. Run addLiteralMask.p.
        proenv>mpro mysports22 -U AdminUser@OEDomain -P AdminPass123 addLiteralMask.p
      For more information about literal mask, see Literal mask.
    3. Partial mask—To configure the partial mask (prefix P:), the following example code uses the setDDMConfig() method and the #DDM_SEE_ContactInfo authorization tag for the phone field of the Customer table.
      USING OpenEdge.DataAdmin.DataAdminService FROM PROPATH.

DEFINE VARIABLE service AS DataAdminService NO-UNDO. 
DEFINE VARIABLE lResult AS LOGICAL NO-UNDO.

service = NEW DataAdminService(LDBNAME("DICTDB")).
lResult = service:setDDMConfig("customer","phone","P:0,X,4","#DDM_SEE_ContactInfo").

MESSAGE "Added Partial mask".
QUIT.

      1. Save the example code as addPartialMask.p.

      2. Run addPartialMask.p.
        proenv>mpro mysports22 -U AdminUser@OEDomain -P AdminPass123 addPartialMask.p
      For more information about partial mask, see Partial mask.
    4. Null mask—To configure the null mask (prefix N:), the following example code uses the setDDMConfig() method and the #DDM_SEE_ContactInfo authorization tag for the address field of the Customer table.
      USING OpenEdge.DataAdmin.DataAdminService FROM PROPATH.

DEFINE VARIABLE service AS DataAdminService NO-UNDO. 
DEFINE VARIABLE lResult AS LOGICAL NO-UNDO.

service = NEW DataAdminService(LDBNAME("DICTDB")).
lResult = service:setDDMConfig("customer","address","N:","#DDM_SEE_ContactInfo").

MESSAGE "Added Null mask".
QUIT.

      1. Save the example code as addNullMask.p.

      2. Run addNullMask.p.
        proenv>mpro mysports22 -U AdminUser@OEDomain -P AdminPass123 addNullMask.p
      For more information about null mask, see Null mask.
  9. To initiate the application of masks on the designated fields, activate DDM:
    proenv>proutil mysports22 -C activateddm
    ACTIVATEDDM ensures that the DDM policies you set up are honored. All connected clients must comply with the policies and mask configurations that have been set up.

    For more information, see PROUTIL ACTIVATEDDM qualifier.

  10. View data from the Customer table.

    1. Save the following example code as findFirstCustomer.p. This code displays the first row of the Customer table, which includes the Custnum, Name, Address, State, City, Postalcode, and Phone fields. 

      FIND FIRST Customer.
DISPLAY custnum name address state city postalcode phone WITH 1 columns.
											
PAUSE 60.
QUIT.
    2. Run findFirstCustomer.p as AdminUser.
      proenv>mpro mysports22 -U AdminUser@OEDomain -P AdminPass123 findFirstCustomer.p
      Output for AdminUser@OEDomain: 
      Cust Num: 3000
Name: Lift Tours
Address: 276 North Drive
State: MA 
City: Burlington
Postal Code: 01730
Phone: (617) 450-0086
      AdminUser can access and view unmasked data in the DDM-configured fields.
    3. Run findFirstCustomer.p as GeneralUser.
      proenv>mpro mysports22 -U GeneralUser@OEDomain -P GeneralPass123 findFirstCustomer.p
      Output for GeneralUser@OEDomain: 
      Cust Num: 3000
Name: Lift Tours
Address: ?
State: XX 
City: MASKED
Postal Code: 01730
Phone: XXXXXXXXXX0086
      GeneralUser views masked data in the DDM-configured fields.
Note:

  • For more information about how to deactivate or disable DDM, see PROUTIL DEACTIVATEDDM qualifier and PROUTIL DISABLEDDM qualifier.

  • The IDataAdminService interface provides a set of methods that enable the execution of CRUD operations pertaining to DDM. These methods are utilized for managing:
    • User-defined roles
    • Users
    • Role grants or user-to-role mapping
    • Authorization tags
    • Setting or unsetting the mask and authorization tag for any field in a table
    For more information on the IDataAdminService methods, see IDataAdminService interface.