FedRAMP and Restricted-Network Deployment

When to use this guide

Use this guide when deploying Trimble Access Management (TAM) in FedRAMP or other restricted-network environments where the appliance must not contact TAM Command & Control (C&C) servers.

In these environments, TAM supports offline mode only. Policy bundles are loaded from a local path or from an S3 bucket in your AWS account. The appliance does not register with TAM, does not download bundles from TAM, and does not report status back to TAM.

Supported deployment variants

Offline mode is supported across all three appliance variants:

• Docker appliance
• Embedded TAM SDK
• AWS Lambda Extension

Step-by-step run instructions for each variant are in Run Appliance. This guide focuses on FedRAMP-specific constraints and configuration.

Prerequisites

Before deploying in a FedRAMP environment, ensure you have:

1. Application credentials — CLIENT_ID and CLIENT_SECRET from Trimble Cloud Console. These are still required at startup for Trimble Identity token validation on incoming requests, even in offline mode.
2. An approved policy bundle — a .tar.gz artifact containing your registered policy packages. Obtain this bundle from a TAM environment outside the restricted network (for example, Stage or Prod) before deploying offline.
3. S3 bucket access — an S3 bucket in your FedRAMP-authorized AWS account to store the policy bundle and optional offline cache configuration.
4. IAM permissions — the appliance execution role or AWS profile must have s3:GetObject (and s3:HeadObject) on the bundle and cache config objects.

See Getting Started for the standard onboarding flow (subscribe, register package, register application) which is performed outside the restricted network before going offline.

FedRAMP constraints

Constraint	Offline mode behavior
TAM C&C contact	Disabled — no registration, bundle download, or status reporting
Policy bundle source	Local file path or s3:// URI via BUNDLE_PATH
Bundle updates	Manual — upload a new bundle to S3 and restart, or rely on OPA S3 polling
Remote data cache	Configured via OFFLINE_CACHE_FILE or OFFLINE_CACHE_CONFIG (supports s3://)
Trimble Identity	Still required — incoming requests are validated against Trimble Identity JWKS
External AWS services	S3 (for bundle/cache), optional Redis, optional OTEL — all within your AWS boundary

Reporting behavior

When OFFLINE_MODE=true, TAM reporting to C&C is disabled automatically. You may also set DISABLE_REPORTING=true as a defense-in-depth configuration, but reporting is already off whenever offline mode is active.

Configuration checklist

Set these environment variables for a FedRAMP offline deployment:

Variable	Required	Description
OFFLINE_MODE	Yes	Set to true
BUNDLE_PATH	Yes	Path to .tar.gz bundle — local path or s3://bucket/key.tar.gz
CLIENT_ID	Yes	Application client ID from Trimble Cloud Console
CLIENT_SECRET	Yes	Application client secret
ENVIRONMENT	Yes	Target environment (Stage, Prod, etc.)
API_PORT	Yes (Docker/Extension)	Port for the local decision API
OFFLINE_CACHE_FILE	Recommended	Path or s3:// URI to offline cache config JSON
OFFLINE_CACHE_CONFIG	Alternative	Inline JSON for offline cache config
DISABLE_REPORTING	Recommended	Set to true (defense-in-depth)
AWS_PROFILE	Local dev	AWS profile for S3 access (mount ~/.aws in Docker)
AWS_EC2_METADATA_DISABLED	EC2/Lambda	Set to false to use instance/execution role
BUNDLE_S3_REGION	Optional	Override S3 bucket region detection
AWS_REGION	Optional	AWS region fallback

Obtain and stage offline bundles

1. In a non-restricted environment, complete the Getting Started flow: register your policy package and application.
2. Download the application bundle (.tar.gz) from TAM.
3. Upload the bundle to your FedRAMP-authorized S3 bucket:

aws s3 cp bundle.tar.gz s3://your-fedramp-bucket/policies/bundle.tar.gz

4. (Optional) Generate and upload an offline cache configuration for remote data sources. See Remote Data and the offline cache workflow in Run Appliance — Offline mode.

5. Set BUNDLE_PATH=s3://your-fedramp-bucket/policies/bundle.tar.gz in your deployment configuration.

S3 vs local file

• s3:// URIs — OPA polls S3 for bundle updates (60–120s interval). No local copy is required.
• Local file paths — mount the .tar.gz into the container or Lambda layer. Bundle updates require redeployment or file replacement.
• HTTPS URLs — the appliance downloads the bundle to a temporary local file at startup.

Deploy by variant

Choose your deployment variant and follow the offline instructions in Run Appliance:

Variant	Use when	Offline instructions
Docker appliance	Container/Kubernetes/ECS deployments	Docker — offline
Embedded TAM	Native library in your application process	Embedded — offline
AWS Lambda Extension	Serverless Lambda functions	Lambda Extension — offline

Docker offline example (S3 bundle)

docker run -it -p 8080:8080 \
  -e ENVIRONMENT=Stage \
  -e API_PORT=8080 \
  -e CLIENT_ID=<<your_client_id>> \
  -e CLIENT_SECRET=<<your_client_secret>> \
  -e OFFLINE_MODE=true \
  -e DISABLE_REPORTING=true \
  -e BUNDLE_PATH=s3://your-fedramp-bucket/policies/bundle.tar.gz \
  -e OFFLINE_CACHE_FILE=s3://your-fedramp-bucket/config/offline-cache.json \
  -e AWS_EC2_METADATA_DISABLED=false \
  -v ~/.aws:/root/.aws:ro \
  trimblecloud-tam-appliance-core-docker-local.artifactory.trimble.tools/appliance:version

On EC2 or ECS with an instance/task role, omit AWS_PROFILE and the ~/.aws volume mount. Set AWS_EC2_METADATA_DISABLED=false so the appliance uses the instance role for S3 access.

Health checks and readiness

Verify the appliance is healthy after deployment:

curl http://localhost:8080/health/readyz

• GET /health/livez — returns 200 once the process has started.
• GET /health/readyz — returns 200 only after the policy bundle is loaded and the engine is ready. Returns 503 if the bundle cannot be loaded.

In offline mode, readiness depends on BUNDLE_PATH being valid and readable (local file or S3 preflight check passing). See Appliance Health for details.

Bundle and data.json update workflow

When policies or data.json change in offline mode:

1. Register and build the updated bundle in a non-restricted TAM environment.
2. Upload the new .tar.gz to your S3 bucket (or replace the local file).
3. If using s3:// with OPA polling, the appliance picks up the new bundle within the polling interval (60–120s). For local file paths, restart the appliance.
4. Verify readiness: GET /health/readyz returns 200.
5. Run a known-good decision request to confirm expected behavior.

Troubleshooting

For detailed troubleshooting, see the Troubleshooting guide. Key sections for FedRAMP offline deployments:

Issue	Troubleshooting section
Bundle path or format errors	Invalid or unreadable bundle path, Invalid bundle format
Stale policy decisions	[Local bundle drift (/trimble-access-management/reference/troubleshooting/#local-bundle-drift-offline-modeft-offline-mode)
Startup credential failures	Missing or invalid client credentials
Engine not ready	Policy engine not ready
Mode-specific checks	Health check by deployment mode, Mode-specific notes

Set LOG_LEVEL=DEBUG temporarily to capture detailed startup and S3 preflight logs. Keep OFFLINE_MODE=true unchanged during diagnostics.

Related guides

• Run Appliance — online/offline mode details and variant-specific instructions
• Getting Started — onboarding in non-restricted environments
• Appliance Image — pull the container image
• Embedded TAM SDK Overview
• Lambda Extension Overview
• Remote Data — offline cache configuration for remote data sources