Use Data Sources

ENTERPRISE

One of the key features of Entitlements is to support interfacing with data from your existing systems and infrastructure. For this example, suppose the car dealership has some existing user data made available on the users URL and you want to bring this into the Entitlements system to allow Styra DAS to make decisions based on it. Then click on the users URL to see the data stored in it.

First, you must create a transform that describes how to map the data source into the Entitlements object model.

Create a Policy

To create a new Policy:

1. Navigate to your system menu, expand the transform folder, click the three dots (⋮) next to it, and select Add Policy to start creating a new policy.

   Figure 1 - Create a Policy
   
   

2. Set the Path (required) to transform/http_users.

3. Set the Module name (required) to transform.rego.

   Figure 2 - Add a Policy
   
   

4. In the new Rego file, paste the following code and verify if your screen looks like Figure 3.

   package transform.http_users
   
   users[id] = record {
       in := input[_]
       id := in.username
       record := {
           "name": in.name,
           "email": in.email,
           "geo": in.address.geo
       }
   }
   Figure 3 - `transform.rego` File
   
   

tip

Don’t forget to click on the Publish button, if you have not done so already.

Finally, the transform is created.

Create a Data Source

To create a new data source:

1. Navigate to your system menu, click the three dots (⋮) next to it, and select Add Data Source to start configuring the data source.

   Figure 4 - Add Data Source
   
   

2. Set the data source Type field to HTTPS, Path field to data sources/, and Data source name to http_users:

   Figure 5 - Data Source Form
   
   

3. Scroll down and expand the Advanced drop down list.

   • Data transform: Select Custom.

   • Policy: Enter transform/http_users/transform.rego.

   • Rego query: Enter data.transform.http_users.users.

4. Click on the Add button to add a data source.

   Figure 6 - Advanced Form
   
   

After several minutes, your new data source will pull the URL, download the JSON, and apply the configured transform. Figure 7 shows the expected result.

Figure 7 - HTTP Data Source

Connect Users for Entitlements

To connect users for Entitlements to know about them.

1. Navigate to Your System >> object >> object.rego policy.

   Figure 8 - `object.rego` File
   
   

The set of all users for Entitlements to know about the users object will be the combination of those users retrieved from your new data source, and the sample users. When you are done editing, check if you have clicked on the Publish button to publish your changes.

Replace the following line in the object.rego file:

users := data.global.systemtypes["entitlements:0.1"].library.sample[sample_package].users

With:

sample_users := data.global.systemtypes["entitlements:0.1"].library.sample[sample_package].users
http_users := data.datasources.http_users
users := object.union(sample_users, http_users)

Create a Rule

To create a rule:

1. Navigate to Your System >> Policy >> rules.rego to create a new rule using this data.

2. Click on the Add rule button.

3. Search and click on the Generic Allow/Deny Rule.

4. In the subjects (optional) field, set Samantha and Bret. Here, the users Samantha and Bret have full access to the entire API.

   Figure 9 - Create a Generic Allow/Deny Rule
   
   

5. Click on the Publish button to publish your changes and return to your Entitlements Playground tab.

6. Now, try to change the resource and action fields. Set subject to Samantha or Bret and compare what happens with other users.

Debug Data Source Transforms

It can be difficult to get transforms working correctly for data sources on the first try.

To debug data source transforms:

1. Select your transform.rego file.

2. Click on the Preview button in the top-right corner.

3. Copy-paste an example of your input data into the Input pane in the bottom-left corner of the screen.

4. Finally, click on the Preview button to see the output of your transform.

   Figure 10 - Debug Data Source Transforms