Configuration reference

Overview

credctl stores device identity and cloud provider configuration in a single JSON file:

~/.credctl/config.json

This file is created by credctl init and updated by setup commands (credctl setup aws, credctl setup gcp). File permissions are 0600 (user read/write only). Use credctl reset to remove all configuration and start fresh.

Example configuration

{
  "version": 1,
  "device_id": "SHA256:aBcDeFg...",
  "key_tag": "com.crzy.credctl.device-key",
  "biometric": "any",
  "created_at": "2026-03-02T10:00:00Z",
  "enclave_type": "secure_enclave",
  "public_key_path": "~/.credctl/device.pub",
  "aws": {
    "role_arn": "arn:aws:iam::123456789012:role/credctl-device-role",
    "issuer_url": "https://d1234567890.cloudfront.net",
    "region": "us-east-1",
    "s3_bucket": "credctl-oidc-123456789012"
  },
  "gcp": {
    "project_number": "123456789",
    "workload_pool_id": "credctl-pool",
    "provider_id": "credctl-provider",
    "service_account_email": "credctl@my-project.iam.gserviceaccount.com",
    "issuer_url": "https://d1234567890.cloudfront.net",
    "credential_file_path": "~/.credctl/gcp-credentials.json"
  }
}

Top-level fields

Field	Type	Required	Default	Description
`version`	integer	Yes (auto-generated)	`1`	Configuration schema version.
`device_id`	string	Yes (auto-generated)	—	SHA-256 fingerprint of the device public key. Set by `credctl init`.
`key_tag`	string	Yes (auto-generated)	`com.crzy.credctl.device-key`	Keychain application tag for the Secure Enclave key. Override with `credctl init --key-tag`.
`biometric`	string	Yes (auto-generated)	`any`	Biometric policy for signing operations. Values: `any` (Touch ID with passcode fallback), `fingerprint` (Touch ID only — key invalidated if fingerprints change), `none` (no user verification). Set by `credctl init --biometric`. Cannot be changed after key creation; requires `credctl init --force` to change.
`enclave_type`	string	Yes (auto-generated)	—	Hardware type. Currently `secure_enclave` only. `tpm` support planned for a future release.
`created_at`	string (RFC 3339)	Yes (auto-generated)	—	Timestamp of device identity creation.
`public_key_path`	string	Yes (auto-generated)	`~/.credctl/device.pub`	Path to the exported public key PEM file.
`aws`	object	No	—	AWS configuration block. Set by `credctl setup aws`. See below.
`gcp`	object	No	—	GCP configuration block. Set by `credctl setup gcp`. See below.

AWS configuration fields

The aws block contains the configuration for OIDC federation with AWS. These fields are set automatically by credctl setup aws.

Field	Type	Required	Default	Description
`role_arn`	string	Yes	—	IAM role ARN to assume via `AssumeRoleWithWebIdentity`. Must match `arn:aws:iam::\d{12}:role/.+`
`issuer_url`	string	Yes	—	OIDC issuer URL. Can be a CloudFront URL (`setup aws`), S3 URL (`setup aws-oidc`), or GCS URL (`setup gcp-oidc`). Must be HTTPS.
`region`	string	No	—	AWS region for the STS endpoint. Must be a valid AWS region code (e.g., `us-east-1`).
`s3_bucket`	string	No	—	S3 bucket name where OIDC documents are published.

Credential TTL is determined by the IAM role’s maximum session duration, not by credctl configuration.

GCP configuration fields

The gcp block contains the configuration for Workload Identity Federation with GCP. These fields are set automatically by credctl setup gcp.

Field	Type	Required	Default	Description
`project_number`	string	Yes	—	GCP project number (numeric). Retrieved automatically by `credctl setup gcp`.
`workload_pool_id`	string	Yes	—	Workload Identity Pool ID.
`provider_id`	string	Yes	—	Workload Identity Provider ID within the pool.
`service_account_email`	string	Yes	—	Email of the GCP service account to impersonate. Must match `@.iam.gserviceaccount.com`.
`issuer_url`	string	Yes	—	OIDC issuer URL. Can be the same as the AWS issuer URL, or a GCS URL from `setup gcp-oidc`.
`credential_file_path`	string	No	—	Path to the generated GCP credential config file. Set by `credctl setup gcp-cred-file`.

The audience for JWT signing is derived automatically from project_number, workload_pool_id, and provider_id:

//iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/providers/{provider_id}

Azure configuration will be added in a future release.

File permissions

Path	Permissions	Notes
`~/.credctl/`	`0700`	Directory — user access only
`~/.credctl/config.json`	`0600`	Configuration — user read/write only
`~/.credctl/device.pub`	`0644`	Public key — safe to share
`~/.credctl/oidc/`	`0700`	OIDC documents directory

File layout

~/.credctl/
├── config.json                     # Device and cloud configuration (0600)
├── device.pub                      # Public key PEM (0644)
├── gcp-credentials.json            # GCP credential config (0600, if configured)
└── oidc/                           # OIDC discovery documents (0700)
    ├── .well-known/
    │   └── openid-configuration    # OIDC discovery document
    └── keys.json                   # JWKS (JSON Web Key Set)

Managing configuration

credctl setup aws — sets up all AWS infrastructure (OIDC hosting, IAM resources, AWS CLI profile) and writes the aws configuration block
credctl setup gcp — sets up all GCP infrastructure (OIDC hosting, WIF resources, credential config file) and writes the gcp configuration block
credctl reset — removes all configuration and tears down cloud resources
Manual editing is possible but not recommended (risk of malformed JSON or incorrect values)

credctl setup aws — all-in-one AWS setup
credctl setup gcp — all-in-one GCP setup
credctl reset — remove all config and cloud resources
credctl init — device identity creation
AWS setup guide — configuring AWS OIDC federation
GCP setup guide — configuring GCP Workload Identity Federation
Troubleshooting — configuration error solutions