Skip to content

Latest commit

 

History

History
121 lines (70 loc) · 8.87 KB

auth.md

File metadata and controls

121 lines (70 loc) · 8.87 KB

Azure Auth

Setting up Azure auth for stackql

Setup Azure Browser auth for individual user account / development use of stackql

Using a terminal, enter az login and then follow the login flow in the browser.

Having done this, pass the --auth parameter into stackql with Azure configured to use default auth, like this: --auth='{ "azure": { "type": "azure_default" }, ... }'. Then, Azure auth should proceed transparently.

Setup Azure Service Principal auth for stackql

Using a client secret

Add the AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET environment variables, as per the documentation for the golang SDK.

Having done this, pass the --auth parameter into stackql with Azure configured to use default auth, like this: --auth='{ "azure": { "type": "azure_default" }, ... }'. Then, Azure auth should proceed transparently.

Background and existing implementations

OCI Auth

Type oci_signing_v1 signs requests with the OCI draft-cavage HTTP signature scheme (Authorization: Signature version="1",keyId="<tenancy_ocid>/<user_ocid>/<fingerprint>",algorithm="rsa-sha256",...). GET/DELETE sign date (request-target) host; POST/PUT/PATCH additionally sign content-length, content-type and x-content-sha256.

Credentials are supplied via the --auth context. Two variants:

Raw (twelve-factor) variant

Supply all of tenancy OCID, user OCID, fingerprint and a private key. Every field accepts a literal key (tenancy_ocid, user_ocid, fingerprint, private_key, private_key_path, passphrase, region) or an env var indirection (tenancy_ocid_env_var, user_ocid_env_var, fingerprint_env_var, private_key_env_var, private_key_path_env_var, passphrase_env_var, region_env_var); when the *_env_var key is set it wins over the literal. passphrase and region are optional.

{"oci": {"type": "oci_signing_v1", "tenancy_ocid_env_var": "OCI_CLI_TENANCY", "user_ocid_env_var": "OCI_CLI_USER", "fingerprint_env_var": "OCI_CLI_FINGERPRINT", "private_key_path_env_var": "OCI_CLI_KEY_FILE"}}

The env var names are free-form; the example uses the exact names the OCI CLI reads (OCI_CLI_TENANCY, OCI_CLI_USER, OCI_CLI_FINGERPRINT, OCI_CLI_KEY_FILE, OCI_CLI_PASSPHRASE, OCI_CLI_REGION) so an environment configured for the CLI works unchanged. Terraform users can point the *_env_var keys at their TF_VAR_* names instead, or skip env vars entirely with the config file variant below - it reads the same ~/.oci/config as both tools.

If any of the four raw values is present, all four are required; a partial set fails fast with cannot compose OCI signing credentials: ... and no request is sent.

Config file variant

When no raw value is present, the standard OCI config file convention applies:

{"oci": {"type": "oci_signing_v1", "config_file_path": "/home/user/.oci/config", "profile": "DEFAULT"}}

config_file_path defaults to ~/.oci/config and profile to DEFAULT; passphrase / passphrase_env_var also apply to the config file key. This is the same file used by the OCI CLI and Terraform.

k8s auth

k8s supports an adaptable auth flow client-go credential plugins, which can be and is leveraged by k8s vendors.

Foreign auth patterns

AWS Cross-Account Access

We implemented standard AWS cross-account access using sts:AssumeRole. The client account/user/runner is granted permission to assume a read-only audit role in the target account, while the target role trusts the client principal via a trust policy, optionally guarded by ExternalId. The target role was granted SecurityAudit, S3 read permissions, and Cloud Control (cloudformation:ListResources, cloudformation:GetResource, etc.) permissions so StackQL can perform live control-plane audits using temporary STS credentials rather than long-lived target-account keys. Docs: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html

The --auth JSON string can be configured to assume a foreign role. This relies on assume-role access being configured in the target tenancy/account.

{"aws":{"type":"aws_assume_role","keyIDenvvar":"AWS_ACCESS_KEY_ID","credentialsenvvar":"AWS_SECRET_ACCESS_KEY","aws_role_arn":"arn:aws:iam::123456789012:role/MyRole"}}

Azure Cross-Tenant Access

We implemented Azure cross-tenant access using a multitenant App Registration in the client tenant. The target tenant admin granted consent to the application, which created an Enterprise Application/service principal inside the target tenant. The target tenant then assigned the built-in Reader role to that enterprise application at the subscription or management-group scope. StackQL authenticates using the client application's client_id and client_secret, but requests tokens from the target tenant authority to audit target Azure resources. Docs: https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant

No change to canonical Azure configuration is needed; use the client app ID/secret, the target tenant ID, and the target subscription ID.

GCP Cross-Organization Access

We implemented GCP cross-organization access by creating a service account in the client project and granting that foreign service account IAM roles directly in the target organization/project. The target org/project granted roles such as Viewer, Security Reviewer, and Folder Viewer to the client-owned service account principal, allowing StackQL to audit the target environment while authenticating only with the client-side service account key. Docs: https://cloud.google.com/iam/docs/granting-changing-revoking-access

There is no change to existing Google auth for this.

Overall

Example, presuming the sourced script contains the cited env vars:

source cicd/vol/vendor-secrets/foreign_to_stackql_user.sh

stackql --auth '{"aws":{"type":"aws_assume_role","keyIDenvvar":"AWS_ACCESS_KEY_ID","credentialsenvvar":"AWS_SECRET_ACCESS_KEY","aws_role_arn":"'"${STACKQL_AUDIT_ROLE_ARN}"'"}}' shell

OIDC from github

GHA → cloud federation via each provider's official action; stackql then uses its standard auth types — no federation-specific --auth string needed.

Workflow needs permissions: id-token: write, then per cloud:

AWS — GitHub docs. IAM OIDC provider + role; aws-actions/configure-aws-credentials@v4 with role-to-assume. Session token (AWS_SESSION_TOKEN) is picked up from env automatically — no extra field needed.

--auth '{"aws":{"type":"aws_signing_v4","keyIDenvvar":"AWS_ACCESS_KEY_ID","credentialsenvvar":"AWS_SECRET_ACCESS_KEY"}}'

GCP — GitHub docs. Workload Identity Pool + Provider, SA bound via both roles/iam.workloadIdentityUser and roles/iam.serviceAccountTokenCreator (the access-token mint path needs Token Creator on top of WIU); google-github-actions/auth@v2 with workload_identity_provider + service_account + token_format: 'access_token'. Capture the action's access_token output into an env var (e.g. GCP_ACCESS_TOKEN) for the stackql step. The action's default external_account credentials file isn't consumable by stackql's service_account type.

--auth '{"google":{"type":"bearer","credentialsenvvar":"GCP_ACCESS_TOKEN"}}'

Azure — action docs. Entra app + federated credential (one per org — Azure won't accept repository_owner matching); azure/login@v2 with client/tenant/subscription IDs.

--auth '{"azure":{"type":"azure_default"}}'

Gotchas

  • GCP: use Workload Identity Federation (project-scoped), not Workforce. Impersonation via token_format: access_token needs both roles/iam.workloadIdentityUser and roles/iam.serviceAccountTokenCreator on the SA. GH secret = full provider resource name (projects/.../providers/...).
  • Azure: federated credentials for GHA disallow repository_owner matching → create one credential per org, or regex on claims['sub'].