If you choose to set a database connection identity from a user identity that your application authenticates (instead of OpenEdge or an ABL callback), you must have a domain entry in the domain registry trusted by the OpenEdge database that matches the user's domain, and this domain must be configured with the built-in _extsso authentication system or a user-defined authentication system. In other words, the domain cannot be authentication-enabled.

To set a connection identity that your application authenticates, the database must already be connected with either an OpenEdge default identity or a user identity that OpenEdge has authenticated in an authentication-enabled domain. Also, any user identity that your application authenticates has no OpenEdge-supported functional identity until you specifically validate and set that identity using an SSO operation on the sealed client-principal.

To validate and set an application-authenticated database connection identity:

1. Build the session domain registry using methods of the SECURITY-POLICY system handle (typically done at session startup).
2. Input the required user credentials, including an indication of the security domain and a passphrase (example).
3. Create and initialize a client-principal object with appropriate values associated with the input user credentials to set the object USER-ID, DOMAIN-NAME, SESSION-ID, and any other attributes or application properties (using the SET-PROPERTY( ) method.
4. Authenticate the required user credentials through the external authentication system.
5. If the authentication succeeds, proceed to step 6. If the authentication fails, invalidate the client-principal object with the AUTHENTICATION-FAILED( ) method and exit these steps accordingly.
6. Seal the client-principal object using the domain access code configured for the security domain in the session domain registry, starting a user login session for the identity the object represents.
   Note: The authenticated identity has not yet been assigned to any resource yet.
7. Assert and validate the authenticated user identity represented by the sealed client-principal object in an SSO operation for the database connection using the ABL SET-DB-CLIENT function. The SET-DB-CLIENT function validates the client-principal object against the database trusted domain registry in order to set the corresponding database connection identity. Optionally, you can invoke SET-DB-CLIENT without specifying a database connection and OpenEdge validates and (if valid) sets the identity against the database trusted domain registry for each active database connection in the session.
8. Manage the rest of the user login session as usual. For more information, see Starting and maintaining user login sessions.

Thus, you might use a code fragment such as this, which starts up an application-authenticated user login session in order to set a database connection identity for a connected inventory database. The bold-faced code features the user login session management and authentication elements, as shown:

Login session for an externally authenticated database connection ID

DEFINE VARIABLE cAccessCode AS CHARACTER NO-UNDO.
DEFINE VARIABLE cPassword   AS CHARACTER NO-UNDO.
DEFINE VARIABLE cUserID     AS CHARACTER NO-UNDO.
DEFINE VARIABLE hAuthProc   AS HANDLE    NO-UNDO.
DEFINE VARIABLE hCP         AS HANDLE    NO-UNDO.

/* Declare external authentication functions */
FUNCTION authenticateMyUser RETURNS LOGICAL 
  (INPUT cUserID AS CHARACTER, INPUT cPassword AS CHARACTER) IN hAuthProc.
FUNCTION getAccessCode RETURNS CHARACTER INhAuthProc.

/* Get user ID/password and instantiate external authentication object,
   which also provides the authentication domain access code */
...
cUserID = ...
cPassword = ...
RUN MyAuthentication.p PERSISTENT SET hAuthProc.
cAccessCode = getAccessCode().

/* Create and initialize a client-principal for use with an authentication
   domain in the database domain registry */
CREATE CLIENT-PRINCIPAL hCp.
ASSIGN
  hCP:SESSION-ID  = "Inventory:" + cUserID + STRING(NOW)
  hCP:USER-ID     = cUserID
  hCP:DOMAIN-NAME = "DatabaseUsers".

/* Authenticate and login database connection ID
   session for the single database connection */
If authenticateMyUser(cUserID, cPassword) THEN DO:
  hCP:SEAL(cAccessCode).
  IF NOT SET-DB-CLIENT(hCP) THEN DO:
    hCP:LOGOUT().
    cRetVal = "User ID not valid DB connection ID".
  END.
END.
ELSE DO:
  hCP:AUTHENTICATION-FAILED("User not authenticated.").
  cRetVal = hCP:LOGIN-STATE + ": " + hCP:STATE-DETAIL.
END.
/* Handle results of authentication */
IF hCP:LOGIN-STATE = "LOGIN" THEN DO: /* Do Inventory stuff... */
  ...
  /* Clear the database connection ID to end the login session */
  hCP:LOGOUT().
  DELETE OBJECT hCP.
END.
ELSE DO: /* Exit with failure message */
  RETURN cRetVal.
  DELETE OBJECT hCP.
END.

In this fragment, the domain access code used by the application is maintained and returned by the same authentication procedure (MyAuthentication.p) that authenticates the user identity. This value, returned using the getAccessCode user-defined function, must match the access code configured for the authentication domain entry in the database trusted domain registry.

Also in this code fragment, the setting of the SESSION-ID attribute, which includes the value of STRING(NOW), while valid is not necessarily unique. If you enable auditing for the application, where unique references are more important, use the GENERATE-UUID function (or for a multi-tier application, the client context ID) to set the SESSION-ID attribute. For more information, see Creating and managing unique object identities.