> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niteshift.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Connect an environment to cloud services with OpenID Connect, AWS and Azure identities, or stored secrets.

An integration gives a task access to a service outside its [environment](/environment-configuration/overview).

## OpenID Connect (OIDC) tokens

A task can mint a short-lived Niteshift identity token for an audience chosen by the external
service. You can ask the agent to generate a token for you or you can run this commend in the task termina,
replacing the audience with the one that service expects:

```bash theme={"dark"}
ns oidc-token --audience 'example-cloud-service.com'
```

The issuer is `https://identity.niteshift.dev`
([discovery document](https://identity.niteshift.dev/.well-known/openid-configuration)).

| Claim | Meaning |
| - | - |
| `sub` | Subject in the form `org:<org_id>:environment:<environment_id>`. It is shared by tasks in the same organization and environment. |
| `environment_id` | ID of the environment selected for the task. |
| `user_id` | User associated with the task. System-issued tokens for cache builds omit this claim. |
| `org_id` | ID of the organization that owns the environment. |

Minting a token does not grant access to another service by itself; configure access for the identity on the service side.

## AWS

Niteshift's AWS integration configures AWS tools and libraries to authenticate with Niteshift using
an OIDC token. Niteshift handles obtaining and refreshing credentials.

The easiest way to set up the configuration is to ask the agent to help you integrate with AWS. It will
help you set up configuration both within Niteshift and AWS, and it will help you verify that it's working.

Within Niteshift, the configuration lives within `settings.yaml`. You can declare each AWS profile that you want to configure:

```yaml settings.yaml theme={"dark"}
version: 1
integrations:
  aws:
    - profile: default
      roleArn: arn:aws:iam::111122223333:role/NiteshiftDevelopment
      audience: sts.amazonaws.com
      region: us-east-2
    - profile: analytics
      roleArn: arn:aws:iam::444455556666:role/NiteshiftAnalytics
      audience: sts.amazonaws.com
      region: eu-west-1
```

You need to have at least one `default` profile.

On the AWS side, you'll need to configure an OIDC identity provider for `identity.niteshift.dev`,
and a trust policy for each role to trust tokens from that issuer. [AWS's OIDC role guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
explains the AWS-side trust and permissions policies.

Run `ns oidc-token --inspect --audience 'sts.amazonaws.com'` in the Niteshift terminal tab to see the trust values
without printing the token.

## Azure

Niteshift also have a native Azure integration that configures Niteshift environments to integrate with Azure
using an OIDC token. Niteshift handles fetching and refreshing credentials.

The easiest way to set up the integration is to ask the agent to do it. It will help you with the configuration
both within Niteshift and within Azure, and it will verify that it works.

For the Niteshift configuration, declare the Microsoft Entra tenant ID and the identity's client ID in the
environment's committed `settings.yaml`:

```yaml settings.yaml theme={"dark"}
version: 1
integrations:
  azure:
    tenantId: 11111111-1111-1111-1111-111111111111
    clientId: 22222222-2222-2222-2222-222222222222
```

Within Azure, you'd need to configure a federated credential and assign permissions to Azure resources
that it needs. See [Microsoft
Entra's federated credential guide](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
for the Azure-side trust setup.

Run `ns oidc-token --inspect --audience 'api://AzureADTokenExchange'` in the Niteshift terminal tab to see the trust
values without printing the token.

## Environment variable secrets

You can also integrate with systems by having Niteshift store API keys or secrets. You can store secrets as
[environment variables](/environment-configuration/overview#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](/environment-configuration/services#environment). Service secret
references cannot read **Agent** scope variables.