Skip to main content
An integration gives a task access to a service outside its environment.

​
Quick start for AWS, GCP, and Azure

Niteshift configures the AWS, Azure, and GCP SDKs and CLIs for you. The agent will guide you through the process:
  1. Start a task in the environment you want to connect.
  2. Ask the agent to connect AWS, Azure, or GCP. Specify the account or project, the resources, and the operations it needs. For example:
    Connect this environment to AWS so tasks can read objects in my reports S3 bucket.
  3. The agent writes the Niteshift configuration, helps you configure cloud-side trust and permissions scoped to this environment, and verifies access with an intended resource operation.
See the provider reference for configuration and cloud-side trust details.

​
Workload identity federation with OpenID Connect (OIDC) tokens

Many services can trust short-lived, Niteshift-issued OIDC tokens. Examples: The token issuer is https://identity.niteshift.dev (discovery document). Each token is minted for an audience, which is the value the target service tells you to expect. To see the exact claim values for your environment, ask the agent or run this in the task terminal:
To mint a token, ask the agent or run:
Minting a token does not grant access to another service by itself; configure access for the identity on the service side.

​
Environment Variable Secrets

You can also integrate with systems by having Niteshift store API keys or secrets. You can store secrets as environment variables in Niteshift settings, outside the repository. The Setup script scope is available to .niteshift/setup and .niteshift/resume. The separate Agent scope is available to the agent and its terminal, including commands it runs. Services do not inherit either scope. To give a managed service a secret, store it in Setup script and reference its name with secret in the services.yaml file. Service secret references cannot read Agent scope variables.

​
Reference

​
AWS

Niteshift obtains and refreshes credentials for AWS tools and libraries using OIDC. Within Niteshift, the configuration lives within settings.yaml. You can declare each AWS profile that you want to configure:
settings.yaml
You need to have at least one default profile. For each AWS profile, run ns oidc-token --inspect --audience '<configured-audience>' in the Niteshift terminal tab with that profile’s audience (for example, sts.amazonaws.com). This shows the exact iss, aud, and environment-specific sub without printing the token. In each role’s AWS account, configure an OIDC identity provider using the inspected iss and register the inspected aud as an allowed audience. Each role’s trust policy should require both the exact inspected aud and sub, as shown in the example below. Trusting only the shared issuer and audience does not restrict access to your Niteshift environment. Use this trust policy, replacing <role-account-id> with the role’s AWS account ID and <inspected-aud> and <inspected-sub> with the exact inspected values. The sub has the form org:<org_id>:environment:<environment_id>; copy the entire inspected value without wildcards.
Repeat this setup for every configured role and account. AWS’s OIDC role guide covers trust and separate role permissions policies.

​
Azure

Niteshift obtains and refreshes OIDC tokens for Azure workload identity authentication. For the Niteshift configuration, declare the Microsoft Entra tenant ID and the identity’s client ID in the environment’s committed settings.yaml:
settings.yaml
Run ns oidc-token --inspect --audience 'api://AzureADTokenExchange' in the Niteshift terminal tab to see the trust values without printing the token. On the app registration identified by clientId, add a federated credential with the exact inspected iss, aud, and environment-specific sub. Microsoft Entra checks all three values with case-sensitive matching. Replace the placeholders below with the inspected values:
The subject is the entire inspected org:<org_id>:environment:<environment_id> value. Use a distinct credential name for each environment you authorize. Separately grant the app’s service principal only the permissions it needs on the intended Azure resources. See Microsoft Entra’s federated credential guide for the Azure-side setup.

​
GCP

Niteshift integrates natively with GCP tools via Application Default Credentials (ADC). It relies on the ns cloud-creds gcp executable helper to generate a short-lived Niteshift OIDC token, which Google exchanges for access credentials. On the Niteshift side, the integration is configured with an entry in the environment’s committed settings.yaml. Set one workload identity provider using its project number. Add serviceAccountEmail only if the workload will impersonate a service account:
settings.yaml
Inspect the audience derived from your configured provider: https://iam.googleapis.com/ followed by the provider path. For the example above, run:
In Google Cloud, create a workload identity pool and an OIDC provider using the inspected iss and aud. Map google.subject from assertion.sub and restrict the provider to the exact inspected environment-specific sub with an attribute condition. Trusting only the issuer and audience does not restrict access to your Niteshift environment. For an existing pool, create its provider with the following command. Replace the project, pool, and provider placeholders with the values from settings.yaml, and the claim placeholders with the exact inspected values:
Grant resource permissions to this environment’s subject principal, using the project number of the project that owns the pool and the entire inspected sub:
For direct access, grant that principal only the required resource roles. For service account impersonation, grant it roles/iam.workloadIdentityUser on the selected service account and grant resource permissions to that service account. Avoid pool-wide wildcard grants. Google’s Workload Identity Federation guide covers provider setup and both access methods.