HowTo: Define an API object with a security scheme

This article shows you the steps to define an API object with a security scheme. To do so, follow the steps below:

Step 1. API object definition

Consider the following two-level Transaction object configured as a Business Component:

Customer
{
    CustomerId*      (Autonumber property = Yes)
    CustomerName
    CustomerLastName
    CustomerPhone
    CustomerEmail
    CustomerLastAccountId
    Account
    {
       AccountId*
       AccountPassword
       AccountBalance
       AccountStatus    (Type:Boolean)
    }
}

The Transaction has the following rule defined:

Serial(AccountId,CustomerLastAccountId,1);

Suppose you want to see if a Customer has a certain active account and the Balance of that account. To do this, create a Procedure object called ShowCustomerInfo with the following sections:

Variables:

Account          (Type:Customer.Account)
AccountBalance   (Type:Attribute:AccountBalance)
AccountId        (Type:Attribute:AccountId)
AccountPassword  (Type:Attribute:AccountPassword)
AccountStatus    (Type:Attribute:AccountStatus)
Customer         (Type:Customer)
CustomerId       (Type:Attribute:CustomerId)

Rules:

Parm(in:&CustomerId, in:&AccountId, in:&AccountPassword, out:&AccountBalance, out:&AccountStatus);

Source:

&Customer.Load(&CustomerId)
&Account = &Customer.Account.GetByKey(&AccountId)
&AccountBalance = &Account.AccountBalance
&AccountStatus = &Account.AccountStatus

Create an API object called APICustomer and define the following:

Variables:

AccountBalance       (Type:Attribute:AccountBalance)
AccountId            (Type:Attribute:AccountId)
AccountPassword      (Type:Attribute:AccountPassword)
AccountStatus        (Type:Attribute:AccountStatus)
CustomerId           (Type:Attribute:CustomerId)

Service Source:

Customer{
      CustomerInfo(in:&CustomerId, in:&AccountId, in:&AccountPassword, out:&AccountBalance, out:&AccountStatus)
      => ShowCustomerInfo(&CustomerId, &AccountId, &AccountPassword, &AccountBalance, &AccountStatus);
    }

Step 2. Defining the security scheme

To enable GeneXus Access Manager (GAM), set the Enable Integrated Security property to True at version level. Next, select the Authentication or Authorization value for the Integrated Security Level property in the API object. Then, perform a Rebuild All.

If you select the Authorization value, you must define the role and the permissions associated with that role. To facilitate the assignment of permissions to users, you can modify the Permission Prefix property to easily identify the permission and assign it to a specific user.

In addition, by using the Authorization value, you have the option to generate specific permissions for each method within the API object. This allows you to assign individual permissions to particular methods, providing greater granularity in access control and system security.

See Also

HowTo: Configure the API object security scheme
HowTo: Access secure REST services defined via API Objects