End-To-End Example

This example will walk you through creating an application, policy, and evaluate the policy using the dev environment. If you’re using Windows, please download Powershell 7 for this example.

1. Create Application

First, we will need an application registered with Trimble Cloud Console and retrieve credentials. These credentials are needed for all Server API calls and starting up the Appliance.

• Click on the Pre Prod tab in Applications
• Click “Add Application.”
• Check “Service Application” and fill out the required information (Ensure Use Client Credentials is checked).
• Click “Complete” to finish the registration.

Note

You should record the Client ID and Client Secret as they will be used for future calls. Treat Client Secret just as you would a password.

2. Create Rego Policy File

We will now create a policy that the application will use.

Note

Each policy namespace must be globally unique. Once a namespace is taken, other applications cannot overwrite it, but can include them as part of their application.

Create a file using a unique name “your_namespace.rego” and copy and paste the following for the decision endpoint:

package <your_namespace>

default allow := false

allow {
  input.caller_auth.claims.iss == "https://stage.id.trimblecloud.com"
  input.path == "/path"
  input.method == "GET"
}

Replace <your_namespace> with a unique namespace of your choosing.

3. Create Rego Policy Test File

In order to register the policy, we must have unit tests and Rego code coverage in place. Create the file “your_namespace_test.rego” and copy and paste the following for test coverage:

package <your_namespace>

import future.keywords

test_permission_denied if {
    not allow
        with input as {"method": "POST", "path": "/path", "caller_auth":{"claims": {"iss": "https://stage.id.trimblecloud.com"}}}
}

test_permission_allowed if {
    allow
        with input as {"method": "GET", "path": "/path", "caller_auth":{"claims": {"iss": "https://stage.id.trimblecloud.com"}}}
}

Replace <your_namespace> with a unique namespace of your choosing from Step 2

4. Download CLI SDK

Download the CLI SDK. This will be used to register packages and applications.

5. Register Policy Package

We can now register the policy so that it can be validated and used by the appliance. For this example, we will use the SDK CLI. Run the following in a terminal and replace <your_consumer_key> and <your_consumer_secret> with the values from Trimble Cloud Console and <your_namespace> with a unique namespace of your choosing from Step 2.

./tam package register --environment Stage--consumerKey <your_consumer_key> --consumerSecret <your_consumer_secret> --packageNamespace <your_namespace> --pathToFiles ./<your_namespace>.rego --pathToTestFiles ./<your_namespace>_test.rego

For information on deploying policies via CI/CD workflows, see Policy Deployment.

Note

When incorporating HTTP calls within Rego files, it’s essential to register the package with information about the Remote Data Source. This ensures proper communication and data retrieval during policy evaluation. Below are the steps and parameters required for this registration with remote data sounce’s information:

To register your package with a Remote Data Source, include the following parameters:

• remoteDataSourceUrls: Specifies the URLs of the remote data sources your policies will access.
• remoteDataSourceExpirations: Sets the expiration time for the cached data from the remote source. Format the expiration time as HH:MM:SS.
• remoteDataSourceScopes: Defines the scope(s) within which the remote data source will be accessible. This can be a specific scope or left empty for broader access.

When specifying the --remoteDataSourceScopes parameter:

A scope can either be an explicitly defined string that matches a valid scope of your application or an empty string "" to indicate no specific scope limitation. Ensure that the scope value is valid as per your application’s requirements. Invalid scopes will result in errors and prevent successful registration.

./tam package register --environment Stage--consumerKey <your_consumer_key> --consumerSecret <your_consumer_secret> --packageNamespace <your_namespace> --pathToFiles ./<your_namespace>.rego --pathToTestFiles ./<your_namespace>_test.rego --remoteDataSourceUrls <https://reqres.in> --remoteDataSourceExpirations <00:00:20> --remoteDataSourceScopes <test>

6. Register Your Application

Once the policy package is registerd, you will need your application registered with TAM in order to create a bundle for your appliance(s) based upon the policy packages your application will use. Run the following in a terminal and replace <your_consumer_key> and <your_consumer_secret> with the values from Trimble Cloud Console and <your_namespace> with a unique namespace of your choosing from Step 2.

./tam application register --environment Stage--consumerKey <your_consumer_key> --consumerSecret <your_consumer_secret> --namespaces <your_namespace>

7. Retrieve Authorization Token

Retrieve your access token for rule evaluation. Run the following in a terminal and replace <your_consumer_key> and <your_consumer_secret> with the values from Trimble Cloud Console:

curl -d "grant_type=client_credentials&scope=tam-dev" -u <your_consumer_key>:<your_consumer_secret> -H 'Content-Type: application/x-www-form-urlencoded' https://stage.id.trimblecloud.com/oauth/token

Copy the access_token parameter to be used as the bearer token in rule evaluation.

8. Create Input

Create test input for rule evaluation. This will simulate what will be input when using Gin or ASP.NET Core middleware or when using the API / SDK directly. Create the file input.json and copy and paste the following for its contents and replace <access_token> with your token from Step 8:

{
    "input": {
        "method": "GET",
        "path": "/path"
    },
    "auth": "Bearer <access_token>"
}

9. Run Appliance

Run the following in a terminal and replace <your_consumer_key> and <your_consumer_secret> with the values from Trimble Cloud Console

docker run -it -p 8080:8080 \
  -e ENVIRONMENT=Stage\
  -e API_PORT=8080 \
  -e CLIENT_ID=<<your_consumer_key>> \
  -e CLIENT_SECRET=<<your_consumer_secret>> \
  trimblecloud-tam-appliance-core-docker-local.artifactory.trimble.tools/appliance:version

We can now run an appliance locally that will be able to evaulate decisions. Run the following in a terminal and replace <your_consumer_key> and <your_consumer_secret> with the values from Trimble Cloud Console which will launch the appliance on port 8080.

docker run -it -p 8080:8080 -e ENVIRONMENT=Stage-e API_PORT=8080 -e CLIENT_ID=<your_consumer_key> -e CLIENT_SECRET=<your_consumer_secret> trimblecloud-tam-appliance-core-docker-local.artifactory.trimble.tools/appliance:version

If you’d like to run the container in the background, run the following command instead.

docker run -d -it -p 8080:8080 -e ENVIRONMENT=Stage-e API_PORT=8080 -e CLIENT_ID=<your_consumer_key> -e CLIENT_SECRET=<your_consumer_secret> trimblecloud-tam-appliance-core-docker-local.artifactory.trimble.tools/appliance:version

10. Evaluate a Rule

Run the following in a terminal and replace <your_consumer_key> and <your_consumer_secret> with the values from Trimble Cloud Console and <your_namespace> with a unique namespace of your choosing from Step 2:

./tam appliance evaluate --environment Stage--consumerKey <your_consumer_key> --consumerSecret <your_consumer_secret> --applianceUrl http://localhost:8080 --packageNamespace <your_namespace> --rule allow --pathToInputFile ./input.json

If a true result is returned, you have a successful authorization decision!