HowTo: Develop Secure REST Web Services in GeneXus

REST Web Services security is based on Oauth.

Several applications usually expose data update services and data recovery services through REST, so security is very important where privacy of data is a concern.

In GeneXus, the solution to this problem is to use GAM (which hides to the final user the complexity of Oauth technology).

The GAM API provides the way to restrict access to users to REST Web Services defined in the application.

The following is a guide which explains the steps to follow in order to incorporate security to your REST web services, and the way to consume this web services from a GeneXus application also. The way to consume the web services from a non GeneXus application should follow the same main idea.

I. From the perspective of the "REST web services" Knowledge Base

1. Create the REST Web Services of your application. The REST web services can be Business Components, Dataproviders, or procedures, and can expose POST, PUT, DELETE, GET methods.

2. Check the security property in the Knowledge Base (Enable Integrated Security Property). Afterwards, GAM objects will be incorporated to the KB, and a reorganization will be done in order to create GAM repository and an initialization of this repository will be done also. For more details see GeneXus Administration of GAM Repository.

3. Create an application using GAM API (or just using the GAM Backend), in order to identify the "REST web services application" within the GAM repository.

4. Create a user which will have access rights to your application. If you want to restrict the access to some users, you need to configure GAM Permissions.

Note that the GAM Examples include a web application (Backend) which facilitates the administration of Applications, GAM Roles, Users, and Permissions.

5. In order to enable access to the REST services, you need to provide the Client_Id and Client_Secret, user, and password to the consumer.

Take a look at "GAMExampleEntryApplication" object (which belongs to the GAM Examples), to see how to use the GAM API to get the Client_Id and Client_Secret of an application.
In particular if you run GAMExampleWWApplications, when you edit the Application properties of any Application of the Repository, you can see the Client_Id and Client_Secret to access this Application.

See the figure below:

II. From the perspective of the client application, consumer of "REST web services" Knowledge Base

In Oauth there exists the concept of Client (application), User (userId, userPwd), and permissions (Scope= Read, Write,FullControl..).

A GeneXus application which is configured to use GAM; generates a Client Id and Client Secret for each Application.

In order to consume a secure GX REST web service you should:

1. Be provided with Client_Id and Client_Secret of the Application, user, and password with access rigths to this application.

2. Before trying to POST to the web service, you need first to get an access_token. In order to get this access_token you have to POST the Client_Id, Client_Secret, and user credentials. The detailed steps are as follows:

a. First get the access_token. POST to this URL

HTTP://<SERVER>/<APPDIR>/oauth/access_token

with this body:

client id=<client_id>&clientsecret=<client_secret>&grant_type=password&scope=FullControl&username=<user_name>&password=<user_pwd>

Example body:

client id=f719771ad52a42919a221bc796d0d6b0&clientsecret=27c5bf4313d243dd987b3aadb250e63b&granttype=password&scope=FullControl&username=admin&password=admin123

In the HTTPResponse there'll be a json response with the access_token, as this example shows :

{
"access token" : "c9919e10e118" << Access token which will have to be used in all subsequent calls
"scope" : "FullControl"
}

b. Then all the calls to the REST web services should include this header (following the same example):

Authorization: OAuth c9919e10e118

The following is a complete sample code which shows how to GET de products list ("Product" Business Component exposed as REST web service), which is a secure web service (GAM is enabled in the KB).
Client Id and Client Secret are taken from the application defined automatically in GAM Backend.

We use HTTPClient data type to consume the REST web service.

//First get the access_token

&addstring ='client_id=be47d883307446b4b93fea47f9264f88&client_secret=622e2ed94a3f4c909ae959c7df8c2c6d&grant_type=password&scope=FullControl&username=test&password=test'

&httpclient.Host= &server
&httpclient.Port = &port

&httpclient.BaseUrl = &urlbase + '/oauth/'  
&httpclient.AddHeader("Content-Type", "application/x-www-form-urlencoded")
&httpclient.AddString(&addstring)
&httpclient.Execute('POST','access_token')

&httpstatus = &httpclient.StatusCode
msg('Http status: ' + &httpstatus,status)
&result = &httpclient.ToString()

&AccessTokenSDT.FromJson(&result) // Load the AccessToken in a SDT which has this structure (*)

//call Product web service

&httpclient.BaseUrl = &urlbase + '/rest/'

&httpclient.AddHeader('Authorization','OAuth ' + &AccessTokenSDT.access_token)
&httpclient.Execute('GET','Product')

Note:

The grant_type in the json body sent to the "access_token" service maps to the GAM Authentication Types, so "password" means Local Authentication and the other possible values are facebook, twitter, google, ExternalService.

(*)

It's recommended to use HTTPS so the communication channel between client and server is secure.

I. From the perspective of the "REST web services" Knowledge Base

II. From the perspective of the client application, consumer of "REST web services" Knowledge Base

See Also