SecureContext logo

Documentation

Get SecureContext running in your environment in under an hour.

Installation

For most business deployments, a single server is enough. On AWS, the simplest remote path is one EC2 instance plus Systems Manager.

AWS EC2 / SSMRecommended

From your laptop, deploy to an EC2 instance with one AWS CLI command. Assumes Docker is installed and /opt/securecontext/securecontext.yaml already exists on the instance.

terminal
aws ssm send-command \
  --instance-ids i-0123456789abcdef0 \
  --document-name "AWS-RunShellScript" \
  --comment "Deploy SecureContext" \
  --parameters 'commands=[
    "docker pull ghcr.io/secure-context/gateway:latest",
    "docker rm -f securecontext || true",
    "docker run -d --name securecontext --restart unless-stopped -p 8080:8080 -v /opt/securecontext:/config:ro -e SC_CONFIG_PATH=/config/securecontext.yaml ghcr.io/secure-context/gateway:latest"
  ]'
Cloud VM / Docker

Generic single-host deploy for any Linux VM when you are already on the server.

terminal
# On the server, with /opt/securecontext/securecontext.yaml already in place
docker pull ghcr.io/secure-context/gateway:latest


docker run -d \
  --name securecontext \
  --restart unless-stopped \
  -p 8080:8080 \
  -v /opt/securecontext:/config:ro \
  -e SC_CONFIG_PATH=/config/securecontext.yaml \
  ghcr.io/secure-context/gateway:latest
Docker (Local)

Good for local testing on your own machine.

terminal
docker pull ghcr.io/secure-context/gateway:latest


docker run -d \
  --name securecontext \
  --restart unless-stopped \
  -p 8080:8080 \
  -v /path/to/config:/config:ro \
  -e SC_CONFIG_PATH=/config/securecontext.yaml \
  ghcr.io/secure-context/gateway:latest
Kubernetes / Helm
terminal
# Add the Helm repository
helm repo add securecontext https://charts.securecontext.org
helm repo update


# Install with custom values
helm install securecontext securecontext/gateway \
  --namespace securecontext \
  --create-namespace \
  -f values.yaml
Binary
terminal
# Download the latest release
curl -LO https://releases.securecontext.org/latest/securecontext-linux-amd64


# Make executable and run
chmod +x securecontext-linux-amd64
./securecontext-linux-amd64 --config /path/to/securecontext.yaml

Cloud Deployment Guides

Step-by-step cloud deployment playbooks for SecureContext.

Google CloudAvailable

Deploy to Cloud Run with GitHub Actions, Workload Identity Federation, manual sandbox approval, and production-grade checks.

Open GCP deployment guide
AWSAvailable

Deploy to ECS Fargate with ECR and GitHub OIDC (no static AWS keys).

Open AWS deployment guide
AzureAvailable

Deploy to Azure Container Apps with ACR and GitHub federated credentials.

Open Azure deployment guide

Configuration

Configure your tenant name, tool prefix, and basic settings.

securecontext.yaml
# securecontext.yaml
tenant:
  # The display name shown to users
  display_name: "Atlas"
  
  # Prefix for all MCP tools (e.g., Atlas.ask, Atlas.searchSlack)
  mcp_prefix: "Atlas"
  
  # Optional: Custom branding
  branding:
    logo_url: "https://internal.acme.com/Atlas-logo.svg"
    primary_color: "#0ea5e9"


server:
  host: "0.0.0.0"
  port: 8080
  
  # TLS configuration (recommended for production)
  tls:
    enabled: true
    cert_file: "/certs/server.crt"
    key_file: "/certs/server.key"


logging:
  level: "info"
  format: "json"
  
  # Audit logging for compliance
  audit:
    enabled: true
    destination: "stdout"  # or file path, or syslog URL

Connectors

Add connectors to expose your company's knowledge systems.

AWS Bedrock

Use IAM role assumption for secure access.

connectors:
  - type: bedrock
    name: "AI Models"
    config:
      region: "us-east-1"
      model_id: "anthropic.claude-v2"
      
      # IAM role to assume (recommended)
      assume_role_arn: "arn:aws:iam::123456789:role/SecureContextBedrock"
      
      # Or use instance profile / environment credentials
      # use_default_credentials: true

Amazon Q Business

Use Q as an aggregated knowledge connector.

connectors:
  - type: amazon-q-business
    name: "Company Knowledge"
    config:
      application_id: "your-q-application-id"
      region: "us-east-1"
      
      # IAM role with Q Business permissions
      assume_role_arn: "arn:aws:iam::123456789:role/SecureContextQ"

Slack

Configure OAuth token for Slack access.

connectors:
  - type: slack
    name: "Slack"
    config:
      # Bot OAuth token (xoxb-...)
      token: "${SLACK_BOT_TOKEN}"
      
      # Restrict to specific channels (optional)
      allowed_channels:
        - "engineering"
        - "incidents"
        - "product"
      
      # Enable search and posting
      capabilities:
        - search
        - read_messages
        - post_messages  # optional

Jira

Connect to Jira Cloud or Server.

connectors:
  - type: jira
    name: "Jira"
    config:
      base_url: "https://acme.atlassian.net"
      
      # API token authentication
      email: "${JIRA_EMAIL}"
      api_token: "${JIRA_API_TOKEN}"
      
      # Restrict to specific projects
      allowed_projects:
        - "PAYMENTS"
        - "PLATFORM"
        - "INFRA"
      
      capabilities:
        - search
        - read_issues
        - create_issues
        - update_issues

Authentication

SecureContext supports API tokens and enterprise SSO via OIDC.

Need help setting up Google SSO end-to-end? Follow the SSO Setup guide for exact Google Console labels and a field-by-field mapping for `securecontext.yaml`.

API Token

Simple authentication for internal deployments.

auth:
  mode: api_token
  api_token: "${SECURECONTEXT_API_TOKEN}"

SSO (OIDC)

For SecureContext gateway config, use the `oauth` section in your YAML.

oauth:
  oauth_issuer_url: "https://accounts.google.com"
  oauth_client_id: "${OAUTH_CLIENT_ID}"
  oauth_client_secret: "${OAUTH_CLIENT_SECRET}"
  oauth_scopes: "openid profile email"
  oauth_token_ttl_seconds: 3600

Full step-by-step instructions: SSO Setup

mTLS

Certificate-based authentication for high-security environments. Planned.

auth:
  mode: mtls
  
  mtls:
    # CA certificate for client validation
    ca_cert_file: "/certs/ca.crt"
    
    # Map certificate CNs to permissions
    cn_mappings:
      "developer-workstation":
        - "*"
      "ci-runner":
        - "jira:read"
        - "jira:create"

IDE Setup

Generate client-specific install actions for Cursor, GitHub Copilot, Claude Code, Codex, and other MCP-compatible tools.

Quick action

Cursor

Use Cursor's MCP deeplink or drop the same config into its local mcp.json.

Add to Cursor
Config location
~/.cursor/mcp.json or .cursor/mcp.json
Auth expectation
Remote SecureContext should expose OAuth metadata so the client can complete sign-in when first used.
Note
Cursor supports one-click OAuth install for remote HTTP MCP servers.

Manual config

.cursor/mcp.json

.cursor/mcp.json
{
  "mcpServers": {
    "securecontext": {
      "url": "https://securecontext.example.com/mcp"
    }
  }
}

Recommended path: use OAuth for remote SecureContext installs. The install links and commands above assume the gateway publishes MCP and OAuth metadata on the same base URL.

If you haven't configured OAuth yet, start with SSO Setup. After the server is connected, your client should auto-discover tools like Atlas.ask, Atlas.searchSlack, and Atlas.createJiraTicket.

SSO Setup

Configure Google Sign-In for SecureContext in a way that non-technical teams can repeat reliably.

SecureContext uses Google as an identity provider so admins can sign in with existing company accounts. You will create a Google OAuth client once, then copy values into the `oauth` block in `securecontext.yaml`.

  • Google handles identity verification (who the user is).
  • SecureContext handles authorization (what that user can do).
  • Your SecureContext user table still controls actual access.

Before You Start

Prerequisites
  • A Google Cloud project where you can manage OAuth clients.
  • Your SecureContext base URL (local and/or production).
  • An admin email that is already registered in SecureContext.

Redirect URIs to prepare

# Local development
http://localhost:8080/admin/login/callback


# Production example
https://securecontext.example.com/admin/login/callback

The callback URL must match exactly in Google and in your browser entrypoint domain.

Google Console Steps

1. Open Google Auth Platform

In Google Cloud Console, open Google Auth Platform - Clients.

If your project is not fully configured yet, Google may first prompt for Branding/Audience details.

2. Configure Branding and Audience

Complete the Branding and Audience pages. Typical required fields are app name, support email, and test users (while your app is in testing mode).

Non-technical rule: if sign-in is blocked for a teammate, they are usually missing from your app's allowed audience/test users.

3. Create OAuth client

On the Clients page, click Create client. Set application type to Web application.

Under Authorized redirect URIs, add your callback URL(s):

http://localhost:8080/admin/login/callback
https://securecontext.example.com/admin/login/callback

After saving, copy both Client ID and Client secret.

YAML Value Mapping

securecontext.yaml
oauth:
  oauth_issuer_url: "https://accounts.google.com"
  oauth_client_id: "<from Google Auth Platform > Clients > Client ID>"
  oauth_client_secret: "<from Google Auth Platform > Clients > Client secret>"
  oauth_scopes: "openid profile email"
  oauth_token_ttl_seconds: 3600

What each field means

  • oauth_issuer_url: Google's OpenID issuer. For Google Sign-In this is always https://accounts.google.com.
  • oauth_client_id: copy the OAuth client's Client ID from the Google Auth Platform Clients page.
  • oauth_client_secret: copy the OAuth client's Client secret from the same client details.
  • oauth_scopes: requested identity claims. Keep openid profile email unless you have a specific compliance requirement.
  • oauth_token_ttl_seconds: session duration inside SecureContext. Common values: 3600 (1 hour) or 28800 (8 hours).

Apply Config

Save the `oauth` block in your active config file and restart SecureContext. Do not commit real client secrets to git.

terminal
# Example
CONFIG_PATH=./examples/securecontext.local.yaml ./securecontext

Verify & Troubleshoot

  1. Open `/admin/` and click Sign in with SSO.
  2. Complete Google sign-in.
  3. Confirm you return to admin UI successfully.

Common issues

  • redirect_uri_mismatch: callback URI in Google does not exactly match your SecureContext URL.
  • access denied / not registered: user email is not present in SecureContext user table.
  • OAuth app blocked for teammates: add users to your Google app audience/test users.

Reference: Google OAuth 2.0 documentation.

GCP Deployment Guide

Deploy SecureContext to Google Cloud Run with GitHub Actions and a manual sandbox approval step.

TargetCloud Run

This setup uses GitHub Actions release workflow, native GitHub environment approval for sandbox, Google Workload Identity Federation (no static JSON key), and Cloud Run deployment.

Prerequisites

  • GCP project with billing enabled.
  • GitHub repo admin access (for vars, secrets, environments).
  • Cloud Run region selected (example: us-central1).
  • A container image source. If using GHCR, configure Artifact Registry remote repo.

GitHub Config

Repository variables

GCP_PROJECT_ID=project-c28a9970-8bef-4119-a7b
GCP_REGION=us-central1
GCP_CLOUD_RUN_SERVICE=securecontext-gateway
GCP_SANDBOX_ENVIRONMENT=sandbox
GCP_ALLOW_UNAUTHENTICATED=true


# Use one of the following image variables:
# A) Versioned deploys from Artifact Registry repo
GCP_DEPLOY_IMAGE_REPO=us-central1-docker.pkg.dev/<PROJECT_ID>/ghcr-remote/secure-context/gateway
# B) Fixed image tag (simple starter setup)
GCP_DEPLOY_IMAGE=us-central1-docker.pkg.dev/<PROJECT_ID>/ghcr-remote/secure-context/gateway:latest

Repository secrets

GCP_WORKLOAD_IDENTITY_PROVIDER=projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL>/providers/<PROVIDER>
GCP_SERVICE_ACCOUNT=<SERVICE_ACCOUNT_EMAIL>

GCP Setup

1. Enable required APIs

gcloud services enable \
  iam.googleapis.com \
  iamcredentials.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  serviceusage.googleapis.com \
  --project <PROJECT_ID>

2. Workload Identity Federation + deploy service account

Create a workload identity pool/provider for GitHub OIDC, create deploy service account, then grant:

roles/run.admin
roles/iam.serviceAccountUser
roles/artifactregistry.reader
roles/iam.workloadIdentityUser (binding on the deploy service account)

3. Optional: Artifact Registry remote repo for GHCR

gcloud artifacts repositories create ghcr-remote \
  --project <PROJECT_ID> \
  --location us-central1 \
  --repository-format docker \
  --mode remote-repository \
  --remote-docker-repo https://ghcr.io

Sandbox Approval Gate

Use GitHub native environment approval so deploy waits for Approve and deploy from the UI.

  1. Go to GitHub: Settings → Environments.
  2. Create environment: sandbox.
  3. Add required reviewers for that environment.
  4. Ensure workflow deploy job targets sandbox environment.

Deploy

  1. Push to main (or run workflow_dispatch).
  2. Wait for build, publish, and release verification steps.
  3. Approve sandbox deployment in the pending deployment modal.
  4. Wait for Cloud Run deploy and health check completion.

Verify

# Service status
gcloud run services describe securecontext-gateway \
  --project <PROJECT_ID> \
  --region us-central1


# Deploy workflow health check endpoint
curl -fsS https://<cloud-run-url>/admin/api/public

Troubleshooting

  • IAMCredentials API disabled: enable iamcredentials.googleapis.com.
  • Image pull/deploy failed: set GCP_DEPLOY_IMAGE_REPO or GCP_DEPLOY_IMAGE to a valid Artifact Registry image.
  • Artifact read denied: grant deploy service account roles/artifactregistry.reader.
  • Container failed to start: ensure runtime config exists and stdio is disabled for Cloud Run.

What Next

Next cloud guides to add in this docs section:

  • AWS deployment guide (ECR/ECS or App Runner + GitHub OIDC).
  • Azure deployment guide (Container Apps + federated credentials).

AWS Deployment Guide

Deploy SecureContext to AWS ECS Fargate with ECR and GitHub OIDC. This is a minimal starter path.

TargetECS Fargate

No built-in AWS workflow ships with SecureContext yet. Use the template below as your baseline and adapt for your account.

Prerequisites

  • AWS account with permissions for IAM, ECR, ECS, and CloudWatch Logs.
  • GitHub repo admin access for vars and secrets.
  • An ECS cluster and service (Fargate) created.
  • A task definition template committed in your repo.

GitHub Config

Repository variables

AWS_REGION=us-east-1
AWS_ECR_REPOSITORY=securecontext-gateway
AWS_ECS_CLUSTER=securecontext
AWS_ECS_SERVICE=securecontext-gateway
AWS_ECS_TASK_DEFINITION=.github/ecs-task-definition.json
AWS_ECS_CONTAINER_NAME=securecontext

Repository secrets

AWS_ROLE_TO_ASSUME=arn:aws:iam::<ACCOUNT_ID>:role/github-securecontext-deploy

AWS Setup

1. Create ECR repository

aws ecr create-repository \
  --repository-name securecontext-gateway \
  --region us-east-1

2. Create GitHub OIDC IAM role

Trust GitHub OIDC and grant least-privilege permissions for ECR push + ECS deploy.

Required permissions (minimum):
- ecr:GetAuthorizationToken
- ecr:BatchCheckLayerAvailability
- ecr:CompleteLayerUpload
- ecr:InitiateLayerUpload
- ecr:PutImage
- ecr:UploadLayerPart
- ecs:DescribeServices
- ecs:DescribeTaskDefinition
- ecs:RegisterTaskDefinition
- ecs:UpdateService
- iam:PassRole

Deploy

Minimal GitHub Actions job (`.github/workflows/deploy-aws.yml`):

name: Deploy AWS


on:
  workflow_dispatch:
  push:
    branches: [main]


jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4


      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: ${{ vars.AWS_REGION }}


      - id: login-ecr
        uses: aws-actions/amazon-ecr-login@v2


      - name: Build and push image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: ${{ vars.AWS_ECR_REPOSITORY }}
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t "$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" .
          docker push "$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG"


      - name: Force new ECS deployment
        run: |
          aws ecs update-service \
            --cluster "${{ vars.AWS_ECS_CLUSTER }}" \
            --service "${{ vars.AWS_ECS_SERVICE }}" \
            --force-new-deployment

Verify

aws ecs describe-services \
  --cluster <ECS_CLUSTER> \
  --services <ECS_SERVICE> \
  --region <AWS_REGION>


curl -fsS https://<service-url>/admin/api/public

Troubleshooting

  • OIDC auth denied: verify trust policy on AWS_ROLE_TO_ASSUME.
  • ECR push denied: add missing ECR actions to the role policy.
  • Task won't start: check CloudWatch logs and container env/config path.

Azure Deployment Guide

Deploy SecureContext to Azure Container Apps with Azure Container Registry and GitHub federated credentials.

TargetContainer Apps

No built-in Azure workflow ships with SecureContext yet. Use this section as a minimal deploy starter.

Prerequisites

  • Azure subscription with permissions for ACR and Container Apps.
  • GitHub repo admin access for vars and secrets.
  • Resource group and Container Apps environment created.
  • Federated credential configured for GitHub OIDC.

GitHub Config

Repository variables

AZURE_LOCATION=eastus
AZURE_RESOURCE_GROUP=securecontext-rg
AZURE_CONTAINER_APP_ENV=securecontext-env
AZURE_CONTAINER_APP=securecontext-gateway
AZURE_ACR_NAME=securecontextacr

Repository secrets

AZURE_CLIENT_ID=<app-registration-client-id>
AZURE_TENANT_ID=<azure-ad-tenant-id>
AZURE_SUBSCRIPTION_ID=<subscription-id>

Azure Setup

1. Create Container Registry

az acr create \
  --name <ACR_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --sku Basic

2. Create Container Apps environment + app

az containerapp env create \
  --name <ENV_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --location <LOCATION>


az containerapp create \
  --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --environment <ENV_NAME> \
  --image <ACR_NAME>.azurecr.io/securecontext-gateway:latest \
  --target-port 8080 \
  --ingress external

Deploy

Minimal GitHub Actions job (`.github/workflows/deploy-azure.yml`):

name: Deploy Azure


on:
  workflow_dispatch:
  push:
    branches: [main]


jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4


      - name: Azure login (OIDC)
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}


      - name: Build and push image
        run: |
          az acr login --name "${{ vars.AZURE_ACR_NAME }}"
          docker build -t "${{ vars.AZURE_ACR_NAME }}.azurecr.io/securecontext-gateway:${{ github.sha }}" .
          docker push "${{ vars.AZURE_ACR_NAME }}.azurecr.io/securecontext-gateway:${{ github.sha }}"


      - name: Update container app
        run: |
          az containerapp update \
            --name "${{ vars.AZURE_CONTAINER_APP }}" \
            --resource-group "${{ vars.AZURE_RESOURCE_GROUP }}" \
            --image "${{ vars.AZURE_ACR_NAME }}.azurecr.io/securecontext-gateway:${{ github.sha }}"

Verify

az containerapp show \
  --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query properties.configuration.ingress.fqdn -o tsv


curl -fsS https://<container-app-fqdn>/admin/api/public

Troubleshooting

  • OIDC login failed: verify federated credentials for branch/repo in Entra app.
  • ACR push denied: grant AcrPush role to deployment identity.
  • App unhealthy: inspect revision logs with az containerapp logs show.

Next Steps

  • Review our security documentation for best practices
  • Check the knowledge base for tutorials and advanced configurations
  • for custom connector development

Search docs

Jump to any section in documentation.