Setting connection identity with application-performed user authentication
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.
Note: You can set the user identity for multiple database connections using a single client-principal object by configuring database options to have each database use the ABL session domain registry. In this case, the connection identity can be managed along with the ABL session identity (see EstablishingABL session identity). For more information on setting database options to use the session domain registry, see the sections on run-time domain configuration in OpenEdge Getting Started: Identity Management and the online help for setting database options in the Data Administration tools.
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.
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-PRINCIPLE 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 .
