CREATING AND USING THE CLIENT-PRINCIPAL

Transcription

1 CREATING AND USING THE CLIENT-PRINCIPAL Fellow and OpenEdge Evangelist Document Version 1.0 December 2011 December, 2011 Page 1 of 9

2 DISCLAIMER Certain portions of this document contain information about Progress Software Corporation s plans for future product development and overall business strategies. Such information is proprietary and confidential to Progress Software Corporation and may be used by you solely in accordance with the terms and conditions specified in the PSDN Online ( Terms of Use ( Progress Software Corporation reserves the right, in its sole discretion, to modify or abandon without notice any of the plans described herein pertaining to future development and/or business development strategies. Any reference to third party software and/or features is intended for illustration purposes only. Progress Software Corporation does not endorse or sponsor such third parties or software. In the previous video and paper in this series on support for multi-tenancy in OpenEdge 11, Loading Data into Tenant Tables, I loaded data into the new database for each of four tenants, and showed how you can use the SETUSERID function in ABL to connect to the database using the combination of a userid and that user s domain, which provides access to the data for a single tenant. In this paper I show what s going on behind the scenes when the SETUSERID function is run, and how you can explicitly create and use the OpenEdge authentication object, called a Client- Principal, to provide access to a multi-tenant database. To look at what s happening when you establish your user identity with SETUSERID, I ll create a simple ABL procedure (this is saved as MT6_1.p). First the procedure needs a handle variable to hold a reference to a security object. DEFINE VARIABLE hcp AS HANDLE. Following the SETUSERID function, the procedure then uses the GET-DB-CLIENT function to return the underlying security object that has given me access to the EastSports tenant s data, which is a built-in ABL object that has a handle like other built-in objects. SETUSERID("JoeEast@EastSportsUser", "Joe"). hcp = GET-DB-CLIENT("sportsmt"). Displaying the TYPE attribute for the handle reference returned confirms that GET-DB- CLIENT returns a Client-Principal. The Client-Principal is the security object that was introduced in OpenEdge 10.1 as part of our support for auditing. In OpenEdge 11 its use has been extended to support multi-tenancy, where obviously it is essential to assure that users have access only to their tenant s data. The procedure then displays some of the other attributes of the Client-Principal. One is the USER-ID that was used to connect, and also the DOMAIN-NAME. Remember that it s the combination of user id and domain name that uniquely identifies a user. The Client-Principal also holds the TENANT-NAME for the domain the user connects with. This has been retrieved from the schema tables in the database. And each tenant has a numeric TENANT-ID as well that s used internally. Regular tenants like the ones I ve been creating are assigned positive values starting with 1. The default tenant that has access to shared data and the default tenant partition has an id of zero. The LOGIN-STATE attribute tells you the state of the Client-Principal. If you re successfully connected, its value is LOGIN. You December, 2011 Page 2 of 9

3 can also LOGOUT, which prohibits further use of the Client-Principal for authentication. It can also be EXPIRED, if you ve set an expiration time for the Client-Principal, or FAILED if it was invalid for some reason. Here is the procedure: DEFINE VARIABLE hcp AS HANDLE. "Joe"). hcp = GET-DB-CLIENT("sportsmt"). MESSAGE hcp:type SKIP "User -" hcp:user-id SKIP "Domain -" hcp:domain-name SKIP "Tenant -" hcp:tenant-name SKIP "Tenant ID -" hcp:tenant-id SKIP "State -" hcp:login-state VIEW-AS ALERT-BOX. When I run, you see the values for these attributes. I m user JoeEast, my domain is EastSportsUser, that connects me to the EastSports tenant, whose Id is 1, and my state is LOGIN, which really means that I m connected. There are other attributes this example doesn t show you, and the Client-Principal is also extensible so that you can define your own attributes for specialized security situations.when the procedure ran the SETUSERID function, OpenEdge created this Client-Principal for me automatically. And note that I didn t need to know the domain s access code to get in. Openedge does this basically for backward compatibility with earlier use of _User. If you use _User and the _oeusertable authentication system, then the only thing that is checked by SETUSERID is the user id, now qualified by the domain name, and the user s password. The domain access code is simply retrieved from the database for you and plugged into the Client- Principal. So if you re using _User for your security, you re not really getting the benefit of the additional security of the domain access code. Keep that in mind. Later in this paper there s a brief introduction to an alternative way of doing things. December, 2011 Page 3 of 9

4 Back in the DB Admin Console, I want to set up an alternative to using _oeusertable and the _User schema table. On the main detail frame for the database connection is a link to edit authentication systems: This was shown briefly once before, in an earlier session, but there I didn t modify anything, because the first sample domains use the _oeusertable authentication system. Now I m going to create a new one: I just call it ApplAuth, because this represents an authentication and login system that s managed by my application. Now, one way to enhance the security of your application would be to use a type of plug-in on the server side that s called a PAM, for Pluggable Authentication Module. OpenEdge may provide support for these modules in the future, but this is not yet available in OpenEdge For now the December, 2011 Page 4 of 9

5 database does not know anything about the particulars of my new authentication system, so other than an optional description, there s nothing to be done but save it. Now I return to the sportsmt connection, and add a domain for the new authentication system: I call this one EastSportsAppl, to show that it uses the ApplAuth authentication system. It will be a second domain for the EastSports tenant, so I can configure different groups of EastSports users if I want to use different domains with different security systems. Once again I have to define an access code as a kind of password for the domain. In this case I enter the domain name plus the string Code. As with any password, setting this up carefully and protecting it from unauthorized access will be an important part of setting up security for your application. December, 2011 Page 5 of 9

6 That s all I need to do in the Admin Console. Since I m not using _User for this domain, I don t create any users in the tool. Now I want to show you a very simplified example of how your application can create Client-Principal objects of its own to connect to the database with. This is the procedure saved as MT6_2.p. First I need some variable definitions: DEFINE VARIABLE hcp AS HANDLE NO-UNDO. DEFINE VARIABLE cuserid AS CHARACTER NO-UNDO. DEFINE VARIABLE cdomainname AS CHARACTER NO-UNDO. DEFINE VARIABLE cpassword AS CHARACTER NO-UNDO. DEFINE VARIABLE lauthenticated AS LOGICAL NO-UNDO. DEFINE VARIABLE caccesscode AS CHARACTER NO-UNDO. Next I ve created a simple function that represents your application s user authentication mechanism. It doesn t check the username and password; that would be up to you to do. And it simply says that if the domain name the user specifies ends in appl, it appends Code to that and returns that as the domain access code to use: FUNCTION ApplAuth RETURNS LOGICAL (INPUT pcuserid AS CHARACTER, INPUT pcpassword AS CHARACTER, INPUT pcdomainname AS CHARACTER, OUTPUT pcaccesscode AS CHARACTER): IF SUBSTR(pcDomainName, LENGTH(pcDomainName) - 3) = "Appl" THEN DO: pcaccesscode = pcdomainname + "Code". RETURN TRUE. ELSE RETURN FALSE. Now I said this is a highly simplified example. In a later presentation I show a more realistic example of separating responsibilities between client and AppServer and protecting the integrity of the domain access code. Here the access code is available December, 2011 Page 6 of 9

7 on the client, which is not a good idea. But again, this is just to introduce you to the Client-Principal if you haven t used it before. Next the procedure uses the simplest possible user interface to get the userid, the user s password, and the domain name: UPDATE cuserid FORMAT "x(12)" cpassword FORMAT "x(12)" cdomainname FORMAT "x(20)". Once those are entered, the procedure calls the ApplAuth function, and gets a success or failure flag back, along with the access code if the login succeeded. lauthenticated = ApplAuth(INPUT cuserid, INPUT cpassword, INPUT cdomainname, OUTPUT caccesscode). If that succeeds, the code creates an instance of the Client-Principal, just like any other built-in ABL object: IF lauthenticated THEN DO: CREATE CLIENT-PRINCIPAL hcp. The essential method that must be run in that instance is Initialize(). At a minimum you pass the userid and domain to that method, with the usual at sign in between. There are other optional parameters I won t go into here. IF NOT hcp:initialize(cuserid + "@" + cdomainname) THEN MESSAGE "Initialize of Client-Principal failed" VIEW-AS ALERT-BOX. Once the Client-Principal is set up, you then have to Seal() it. To do this you pass in the domain access code. This is the essential security step. Whatever entity in your application knows the domain access code can use it to seal a Client-Principal for that domain, and after that you can use it to gain access to any database that recognizes that domain and its access code. So this is why it s essential to protect the code in a completed application. IF NOT hcp:seal(caccesscode) THEN MESSAGE "Seal failed for User " cuserid VIEW-AS ALERT-BOX. Now that the Client-Principal is sealed, I can use it to establish my user identity with the SET-DB-CLIENT function. ELSE IF NOT SET-DB-CLIENT(hCP) THEN MESSAGE "SET-DB-CLIENT failed for user " cuserid VIEW-AS ALERT-BOX. December, 2011 Page 7 of 9

8 Now I m authenticated in the sportsmt database as an EastSports user, and I can do the FOR EACH Customer again, to verify that I m connected to the right tenant s data: ELSE DO: FOR EACH Customer: DISPLAY CustNum NAME. One more thing. I mentioned that there s a LOGOUT method on the Client-Principal. This doesn t actually log me out of the database connection. What it does is disable this Client-Principal instance from further use, for instance to connect to another database. I should also clean up by deleting the object and erasing the handle s value: hcp:logout(). DELETE OBJECT hcp. hcp =?. Now I can run the whole procedure. Here s the login: Again, I didn t build any user and password checking into the function, so it doesn t matter what I enter here. Or for the password either. But I do need to enter a domain name that ends with appl: December, 2011 Page 8 of 9

9 When I continue, I ve been authenticated as a user in the EastSportsAppl domain, and here are the EastSports customers: That s the introduction to the Client-Principal, and that s all for this presentation. Next I cover a few more basic multi-tenancy topics, including how to define sequences for multi-tenant tables, and how to define groups of tenants who have some of their data in common. December, 2011 Page 9 of 9