BlueDev Identity Deployment Kit

The Bluedev Identity Deployment Kit provides instructions for bringing up a StepCA server to manage OIDC provisioners and handle enrollment requests initiated by bluedev-bouncer on BlueRock hosts.

The StepCA server can be deployed either directly within a BlueRock VM instance or on a separate VM to serve multiple BlueRock instances. The StepCA package contains Docker files for StepCA and Caddy, along with just command scripts for setup and management.

• StepCA: Registers OIDC provisioners for bluedevx sign-in and accept enrollment authentication requests initiated by bluedev-bouncer.

• Caddy (Optional): Handles automatic TLS certificate generation and maintenance from Let's Encrypt for public deployments. For private, VPN-gated network architectures, StepCA can run independently without Caddy by binding directly to a private interface.

StepCA Deployment

Important:

Whether deployed on a BlueRock VM or an independent VM, StepCA can generate TLS certificates using a Public IP address instead of a DNS domain. For successful enrollment, ensure firewall or security group rules permit inbound traffic from BlueRock host instances to the StepCA port via this IP.

Prerequisites and Installation

1. Extract the package source:

   $ mkdir bluedevca
   $ cp /opt/bluerock/bluedev-identity-ca-0.1.0.tar.gz ~/bluedevca/
   $ cd ~/bluedevca/
   $ tar zxvf bluedev-identity-ca-0.1.0.tar.gz

2. Install prerequisites:

   1. For AL2023:

      $ sudo dnf install -y spal-release
      $ sudo dnf install -y just
      $ sudo dnf install docker
      $ sudo usermod -aG docker ec2-user
      $ sudo systemctl enable docker.service
      $ sudo systemctl start docker.service
      $ sudo systemctl status docker
      $ sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/libexec/docker/cli-plugins/docker-compose
      $ sudo chmod +x /usr/local/bin/docker-compose

   2. For Ubuntu:

      $ sudo apt-get update
      $ sudo apt-get install -y docker.io just curl
      $ sudo usermod -aG docker $USER
      $ sudo systemctl enable docker.service
      $ sudo systemctl start docker.service
      $ sudo systemctl status docker
      $ sudo mkdir -p /usr/lib/docker/cli-plugins
      $ sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/lib/docker/cli-plugins/docker-compose
      $ sudo chmod +x /usr/lib/docker/cli-plugins/docker-compose

Configure Environment

Navigate to the compose directory and configure the environment settings:

$ cd compose/
$ cp .env.example .env
$ vi .env

Set the bouncer password matched during BlueRock Host enrollment:

BOUNCER_PASSWORD=<BOUNCER_PASSWORD>

Choose a Deployment Architecture

Configure the .env file based on the required network architecture:

Private Deployment (without Caddy)

Use this configuration for a CA reachable over a VPN-gated private subnet or SSH tunnel (without Caddy). StepCA publishes directly on a specific interface using self-signed TLS certificates generated for the designated private IP.

# Host address the :9000 listener publishes on
STEPCA_BIND_ADDR=<PRIVATE_IP_ADDRESS>

# Host port for the publish + client URL
STEPCA_BIND_PORT=9000

Note:

Avoid setting STEPCA_BIND_ADDR to 0.0.0.0. This configuration generates the leaf certificate without Subject Alternative Name (SAN) information and bypasses strict firewall routing. Specify the exact private IP address and let the subnet's security group serve as the security boundary.

For without caddy deployment, CADDY_DOMAIN should be blank.

Public Deployment (with Caddy)

Use this configuration for a publicly reachable StepCA server using Let's Encrypt or a local CA:

# Public DNS address OR Public IP address of the Step CA VM instance
CADDY_DOMAIN=<STEP_CA_VM_PUBLIC_DNS_OR_PUBLIC_IP>

# Email used for Let's Encrypt registration
CADDY_ACME_EMAIL=<ADMIN_EMAIL>

# Standard incoming ports to allow in AWS Security Group
CADDY_HTTP_PORT=80
CADDY_HTTPS_PORT=443

Note:

When a registered public DNS domain is unavailable, set CADDY_DOMAIN directly to the Public IP address of the VM instance (for example, CADDY_DOMAIN=000.0.000.00). StepCA will include the Public IP in the Subject Alternative Names (SANs) of the certificate so client handshakes validate without certificate naming errors.

For without caddy deployment, CADDY_DOMAIN should be blank.

Configure Google Identity Provisioner

1. Create a Google OIDC Desktop Client App via the Google Cloud Console (Requires admin privileges) to enable Google Workspace integration. To create a Google OIDC app:

   1. Access the Google Cloud Console and select or create a project.

   2. Navigate to APIs & Services, then select Credentials.

   3. Configure the OAuth Consent Screen by selecting the user type (Internal or External) and defining the mandatory fields, such as the App Name and support email.

   4. Select Create Credentials and choose OAuth client ID.

   5. Select Desktop app as the Application type. This automatically sets the redirect URI to http://127.0.0.1. Define a name and select Create.

   6. Copy the generated Client ID and Client Secret.

Important:

For additional context on Google's authentication protocols, refer to the official documentation:

• OAuth 2.0 API Guidelines

• OpenID Connect Overview

1. Copy and edit the Google provider template:

   $ cd providers/
   $ cp provisioner.env.example google.env
   $ vi google.env

2. Configure the required parameters:

   PROVISIONER_NAME=google
   ISSUER_URL=https://accounts.google.com
   CLIENT_ID=<GOOGLE_CLIENT_ID>
   CLIENT_SECRET=<GOOGLE_CLIENT_SECRET>
   ADMINS=<ADMIN_EMAIL_ADDRESS>
   DOMAIN_RESTRICT=<AUTH_DOMAIN>
   BLUEDEV_DOMAINS=<AUTH_DOMAIN>
   DEFAULT_SSH_CERT_DURATION=8h
   MAX_SSH_CERT_DURATION=24h

Google Workspace Provisioner Configuration Variables

Review and define the following variables carefully before executing the provisioner setup script. Incorrect values will prevent successful host enrollment and developer authentication.

Variable	Description	Notes
PROVISIONER_NAME	The internal identifier for the OIDC provisioner within the StepCA configuration.	Example: google
ISSUER_URL	The OpenID Connect discovery endpoint for Google Workspace.	The value must be exactly [https://accounts.google.com](https://accounts.google.com).
CLIENT_ID	The OAuth 2.0 Client ID generated within the Google Cloud Console credentials page.	Required to identify the application to Google's authorization servers.
CLIENT_SECRET	The sensitive OAuth 2.0 Client Secret paired with the designated Client ID.	Must be kept secure and never committed to version control.
ADMINS	A comma-separated list of administrator email addresses authorized to manage the CA.	Example: [e-mail]
DOMAIN_RESTRICT	The specific email domain authorized to authenticate via this OIDC provisioner.	Example: bluerock.io
BLUEDEV_DOMAINS	The domain name utilized for generating the SSH principal mapping.	Typically matches the DOMAIN_RESTRICT value.
DEFAULT_SSH_CERT_DURATION	The standard time-to-live (TTL) validity period assigned to issued SSH certificates.	Example: 8h
MAX_SSH_CERT_DURATION	The absolute maximum validity period permitted for issued SSH certificates.	Example: 24h

Note:

Configuring the BLUEDEV_DOMAINS parameter is mandatory. This variable is required to correctly map and generate the SSH principal during authentication.

Service Bring-Up and Management

Review available commands using just help:

bluedev-identity — CA-side deployment kit

  SETUP
    just up [--no-caddy]              bring step-ca [+ caddy] up; register provisioners
    just add <name>                   register OIDC provisioner from providers/<name>.env
    just remove <name>                remove OIDC provisioner from step-ca

  SHARE WITH DOWNSTREAM
    just fingerprint [<h:p>|--auto]   print CA root SPKI (or full pin URL)
    just bouncer-info                 print bouncer enrollment inputs (URL + name + password)

  MAINTENANCE
    just update [ca|caddy|all]        apply config changes (default: all) — non-destructive
    just rotate-bouncer-password      re-key bouncer provisioner (DESTRUCTIVE: invalidates enrolled bouncers)
    just info                         read-only health + state probe
    just dump-config [ca|caddy|defaults]
                                      print live container config (default: ca)
    just down [--force]               destructive teardown (containers + volumes)

  KIT DEVELOPMENT
    just test [unit|component|all]    run the test gate (auto-detects step-ca for component)

  Per-verb detail:  just <verb> --help

1. Register the OIDC provider and start services:

   $ just add google
   
   $ just up

2. Check health status:

   $ just info

   Expected Output:

   == bluedev-identity info (read-only) ==
   
     filesystem
       [ ok ]   compose/.env present                     
       [ ok ]   BOUNCER_PASSWORD set                     
   
     docker
       [ ok ]   daemon reachable                         
       [ ok ]   compose plugin v2                        
   
     containers
       [ ok ]   step-ca running                          
       [ ok ]   caddy running                            (ec2-3-144-79-172.us-east-2.compute.amazonaws.com)
   
     step-ca api
       [ ok ]   /health 200 ok                           
   
     provisioners
       [ ok ]   google registered                        
   
     bluedev JWK provisioners
       [ ok ]   bluedev-bouncer registered               (dev-host bouncers auth as this)
       [ ok ]   admin (break-glass)                      info-only; not for routine signing
   
   Summary: HEALTHY
   

3. Retrieve the auto-generated CA enrolment string:

   $ just fingerprint --auto

   Output format:

   https://<STEP_CA_VM_PUBLIC_DNS_OR_PUBLIC_IP>:443#fp=<CA_FINGERPRINT_HASH>
   
   ## Example using Public IP:
   `https://000.0.000.00:443#fp=a1b2c3d4e5...`

   For private deployments, the generated fingerprint URL utilizes the specified private IP address. Output format:

   https://<STEP_CA_VM_PRIVATE_IP>:443#fp=<CA_FINGERPRINT_HASH>
   
   ## Example using Private IP:
   `https://x0x.x0.x0.xx:443#fp=a1b2c3d4e5...`

Important:

Executing a destructive teardown regenerates the CA fingerprint and requires re-enrolling the bouncer on all VMs. Do not execute just down --force for routine configuration modifications.

To apply configuration changes to an existing deployment without losing the CA fingerprint, execute the non-destructive update command:

$ just update ca

Modifying Certificate Expiration (TTL)

To extend the session validity period and reduce sign-out frequency, update the Time-to-Live (TTL) settings in the provider configuration.

1. Open the relevant provider environment file (for example, providers/entra.env or providers/google.env).

2. Update the duration parameters to the required validity period (for example, 168 hours). The MAX_SSH_CERT_DURATION value must always be greater than or equal to the DEFAULT_SSH_CERT_DURATION value:

   DEFAULT_SSH_CERT_DURATION=168h
   MAX_SSH_CERT_DURATION=168h

3. Apply the configuration changes by executing the non-destructive update command:

   just update ca

Note:

Updated validity periods take effect upon the next authentication. Existing sessions maintain the current expiration until the next sign-in.

Enrol BlueRock Host

Log in to the BlueRock VM and execute the enrollment command using the generated CA URL:

$ sudo bluedev-bouncer enroll --ca https://<STEP_CA_VM_PUBLIC_DNS_OR_PUBLIC_IP>:443#fp=<CA_FINGERPRINT_HASH> --passoword

Enter the BOUNCER_PASSWORD when prompted

Note:

<STEP_CA_VM_PUBLIC_DNS_OR_PUBLIC_IP> accepts either the domain name or raw Public IP address of your StepCA server. For private deployments without Caddy, the URL will use the StepCA server's private IP address. Ensure the BlueRock host has network connectivity to this private IP (for example, by residing in the same private subnet or being reachable via VPN).

Configure Microsoft Entra ID Provisioner

1. Create an OIDC Desktop App using App Registrations in the Azure Portal to enable Microsoft Entra ID integration. To create a Microsoft Entra ID app:

   1. Access the Azure Portal and navigate to Microsoft Entra ID.

   2. Select App registrations, then select New registration.

   3. Define the application name and select the supported organizational directory account types.

   4. Set the Platform to Public client (mobile & desktop).

   5. Set the Redirect URI to http://127.0.0.1.

   6. Select Register and copy the generated Application (client) ID.

Important:

For detailed architectural context, refer to the official Microsoft identity platform documentation.

1. Create and edit entra.env:

   $ cd providers/
   $ vi entra.env

2. Configure the required parameters:

   PROVISIONER_NAME=entra
   ISSUER_URL=https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration
   CLIENT_ID=<ENTRA_OIDC_APP_CLIENT_ID>
   ADMINS=<ADMIN_EMAIL_ADDRESS>
   DOMAIN_RESTRICT=<AUTH_DOMAIN>
   BLUEDEV_DOMAINS=<AUTH_DOMAIN>
   DEFAULT_SSH_CERT_DURATION=8h
   MAX_SSH_CERT_DURATION=24h

Entra ID Provisioner Configuration Variables

Review and define the following variables carefully before executing the provisioner setup script. Incorrect values will prevent successful host enrollment and developer authentication.

Variable	Description	Notes
PROVISIONER_NAME	The internal identifier for the OIDC provisioner within the StepCA configuration.	Example: entra
ISSUER_URL	The OpenID Connect discovery endpoint for the Microsoft Entra ID tenant.	Replace <TENANT_ID> with the exact Entra tenant ID.
CLIENT_ID	The Application (client) ID generated during the Entra ID app registration process.	Located in the Entra ID application overview panel.
ADMINS	A comma-separated list of administrator email addresses authorized to manage the CA.	Example: [e-mail]
DOMAIN_RESTRICT	The specific email domain authorized to authenticate via this OIDC provisioner.	Example: bluerock.io
BLUEDEV_DOMAINS	The domain name utilized for generating the SSH principal mapping.	Typically matches the DOMAIN_RESTRICT value.
DEFAULT_SSH_CERT_DURATION	The standard time-to-live (TTL) validity period assigned to issued SSH certificates.	Example: 8h
MAX_SSH_CERT_DURATION	The absolute maximum validity period permitted for issued SSH certificates.	Example: 24h

Note:

Configuring the BLUEDEV_DOMAINS parameter is mandatory. This variable is required to correctly map and generate the SSH principal during authentication.

Bring-Up Service

Register the Entra ID provider and start services:

$ just add entra
$ just up

Retrieve Fingerprint and Enroll Host

1. Get the host enrollment string:

   $ just fingerprint --auto

   Expected output:

   https://<STEP_CA_VM_PUBLIC_DNS>:443#fp=<CA_FINGERPRINT_HASH>

2. Log in to the target BlueRock VM and execute enrollment:

   $ sudo bluedev-bouncer enroll --ca https://<STEP_CA_VM_PUBLIC_DNS>:443#fp=<CA_FINGERPRINT_HASH> --password

   Enter the BOUNCER_PASSWORD when prompted

Unenroll a BlueRock Host

If the BlueRock Identity Service was previously configured on a host instance, the bouncer must be unenrolled to prevent configuration conflicts before switching to a different authentication method (such as SSH Key Trust) or decommissioning the environment.

To reverse a host enrollment and clear the Certificate Authority (CA) trust configuration, execute the following command directly on the BlueRock host instance terminal:

$ sudo bluedev-bouncer unenroll

Command Actions:

The unenroll command reverses the enroll process. Upon execution, it performs the following system modifications:

• Removes the bouncer SSH configuration file (/etc/ssh/sshd_config.d/51-bluedev-bouncer-ca.conf).

• Deletes the CA public key located at /etc/bluedev/user_ca.pub (unless the --keep-ca-pubkey flag is specified).

• Removes all host-certificate files (unless the --keep-host-cert flag is specified).

Bluedev Bouncer CLI Reference

The bluedev-bouncer runs directly on the target BlueRock host to handle system setup and CA trust enrollment. Below is the complete command-line interface surface for operator reference.

$ sudo bluedev-bouncer --help

Expected output:

CLI surface of the bouncer.

The binary has exactly two shapes:

- **Session mode** — sshd `ForceCommand` runs the binary with empty argv; clap parses no subcommand; the bouncer reads the verb from `SSH_ORIGINAL_COMMAND` and routes through the wire verb allowlist (`crates/verbs`). The wire cannot reach any operator surface. - **Operator mode** — one of the [`Command`] subcommands. All host-mutation and diagnostic verbs go here for a single uniform surface. Plan 08 (`plans/08-install-subcommand.md`) drove the lifecycle half; `self-check` / `print-paths` / `build-catalog` / `install-catalog-packages` were promoted alongside so the operator-facing CLI doesn't mix flag-style and subcommand-style modes.

Usage: bluedev-bouncer [OPTIONS] [COMMAND]

Commands:
  install                   Install bluedev-bouncer on this host. Performs the host setup: useradd, conffile placement, state-dir creation, sshd snippet two-phase commit, tmpfiles, systemctl reload. Idempotent; requires root
  uninstall                 Uninstall bluedev-bouncer. Reverses `install`. Catalog and packages dirs are preserved unless `--purge`
  enroll                    Opt-in CA trust + (optional) host-cert signing via a CA provisioner. Writes `/etc/bluedev/user_ca.pub`, optionally signs the host's SSH host keys, writes `/etc/ssh/sshd_config.d/51-bluedev-bouncer-ca.conf`. Trust-only path and JWK signing path are both wired
  unenroll                  Reverse of `enroll`. Removes the `51-*` snippet, the CA pubkey at `/etc/bluedev/user_ca.pub` (unless `--keep-ca-pubkey`), and every host-cert file (unless `--keep-host-cert`)
  doctor                    Read-only health probe. Reports install + enroll status, host-cert expiry warnings (<7 days = warn; expired = error), `sshd -t` cleanliness, allowlist shape validity. Exit 0 = clean; 1 = warnings; 2 = errors
  self-check                Operator health probe. Verifies docker daemon reachability, devcontainer CLI on PATH, `git >= 2.25`, allowlist files present, scratch perms, etc. Exit codes per check
  print-paths               Print resolved `[paths]` values from the config file as shell-eval-safe `KEY='value'` lines on stdout. One parser (this binary) owns the TOML schema; downstream scripts read from here
  build-catalog             Pre-build every devcontainer template under `[paths] catalog_root` so subsequent `up` invocations skip the slow image-build step. Writes to `bluedev-primed/<id>:latest`
  install-catalog-packages  Bake every template's `[paths] packages_root` `.deb`/`.rpm` contents into the primed image. Skips `devcontainer build` — `--install-catalog-packages` invokes it internally — so subsequent `up` skips both build AND runtime package install
  link                      Serve one protocol-v2 link connection over stdin/stdout. The v2 sshd `ForceCommand` entry point: reads the handshake from stdin, authenticates from the SSH session environment, and runs the multiplexed dispatch loop until the link closes
  help                      Print this message or the help of the given subcommand(s)

Options:
      --config <CONFIG>
          Path to the bouncer's main config file. Applies to every subcommand that loads config (session mode included)
          
          [default: /etc/bluedev/bouncer.toml]

  -h, --help
          Print help (see a summary with '-h')

View Active bluedev-bouncer Sessions

Execute the bluedev-bouncer sessions command to display all containers managed by the bluedev-bouncer and view active client sessions on the BlueRock host:

$ sudo bluedev-bouncer sessions

CONTAINER ID  NAME                   WORKSPACE                 OWNER                      IMAGE                                      STATE    SESSIONS  CLIENTS
9e224510d573  coral-claude-ar-c1     claude-workload-<ID>      <USER_EMAIL>@<domain>.com  bluedev-primed/coral-claudedesktop:latest  running  1         <CLIENT_IP> (11m)
5f19294b67f5  ubuntu-bluerock        ubuntu-bluerock-<ID>      <USER_EMAIL>@<domain>.com  bluedev-primed/ubuntu-bluerock:latest      running  1         <CLIENT_IP> (15s)
8c998a803c05  ubuntu-bluerock-ar-c2  ubuntu-bluerock-<ID>      <USER_EMAIL>@<domain>.com  bluedev-primed/ubuntu-bluerock:latest      running  2         <CLIENT_IP> (10m), <CLIENT_IP> (3m)