Understanding TAM

title: “TAM Implementation” description: “Implementation of Trimble Access Management.” lead: "" date: 2020-10-13T15:21:01+02:00 lastmod: 2020-10-13T15:21:01+02:00 draft: false images: [] menu: docs: parent: “overview” weight: 106 toc: true

Understanding TAM

Trimble Access Management (TAM) has two portions:

Appliance API
Server API

Overview

What is an Appliance?

An appliance is a container image that runs in your cloud environment and serves an API that you can call in order to make policy decisions.

The appliance handles:

Hosting an API to make policy decisions in your local environment.
Downloading policies and various metadata used to help make policy decisions.
Communicating with remote data sources to query (and cache) information.
Reporting metrics and monitoring.

The appliance can be launched as part of a Kubernetes cluster, AWS Elastic Container service, or as any other configuration as you see fit.

Appliance

The appliance is exposed as:

REST API
Envoy Proxy Authorization Filter.

This allows the caller to choose the best integration method. REST API allows for manual calling to the API or using our SDK (.NET / Go) as an API / middleware (ASP.NET Core / Gin). Alternatively, the Envoy Proxy Filter can act as a front door to your API.

Server API

The server API provides mechanisms for registration of your application and policy packages.

Application Registration

In order for TAM to know what policy packages the Appliance should have, application registration must first occur and be provided a list of policy package namespaces.

As policy packages are updated or new policy packages are added that match the applications policy requirements, they will be used by any currently running or newly launched appliances.

An application must have at least one policy package referenced in order to have a bundle created.

Using Wildcards to Match Multiple Package Namespaces

Wildcards may be used as part of the Application Registration namespace to register all matching namespaces simultaneously instead of one at a time. This is done via using * as the wildcard character. For example, registering the namespace "TrimbleCloudProject*" is the same as registering all matching namespaces such as "TrimbleCloudProjectOne", "TrimbleCloudProjectBeta", and "TrimbleCloudProject3. Wildcards cannot be used in conjunction with namespaces that have pinned package revisions.

Specifying a Specific Package Revision using Namespaces

In addition, package revisions may be specified as part of the namespace during Application Registration to “pin” a specific package to always be used as part of the application’s bundle. This is done by entering the package namespace in Application Registration with the following form: "<namespace_name>:<revision_number>". For example, to make sure your application’s bundle always uses revision 3 of package TrimbleCloudProjectOne you would enter the namespace "TrimbleCloudProjectOne:3" during Application Registration. Just like normal namespaces, multiple pinned revision namespaces and regular namespaces can be used together during Application Registration and any you wish to persist on your application must be entered every Application Registration. Pinned revisions cannot be used in conjunction with namespaces containing wildcards.

Namespaces containing both wildcards and a pinned revision, namespaces with a revision that is not an integer, and other improperly formed namespaces will cause Application Registration to return a 400. If the package the pinned revision specifies fails package validation or does not exist, bundling will fail and Application Registration (and possibly Package Registration) will need to be repeated with correct data.

Package Registration

Policy packages need to be registered and validated before being used to make policy decisions. Once a policy package has been registered with a specific namespace, only the owner of the policy is allowed to make updates to it.

A policy package consists of one or more rego files compressed in zip format. The packageNamespace provided during Package Registration must match the package directive of the rego files being registered.

During registration, a test policy package consisting of one or more rego files compressed in zip format must also be provided. This allows us to perform a validation step of running rego unit tests (written by the package maintainer) in order to prove 100% code coverage and validate correct syntax.

After a policy package has been validated, it is put into service and distributed to all appliances that use the policy provided.