Airplane OpenID Connect (OIDC)

Use Airplane's OIDC provider to authenticate from tasks to cloud providers and other APIs.

Airplane OpenID Connect (OIDC) allows your tasks to authenticate to other APIs (such as AWS, GCP, or your own API) without having to store sensitive, long-lived credentials.

Your Airplane tasks can generate short-lived ID tokens which are passed to a target API to authenticate and "prove" their identity. ID tokens contain subject and claim information specific to the task and runner, allowing for fine-grained access control (e.g. allowing specific tasks to access AWS buckets).

This page documents how to generate Airplane tokens and the token format. For guides on how to integrate OIDC with cloud providers like AWS or your own API, see:

OIDC with AWS

OIDC with GCP

OIDC with your API

Generating tokens

OIDC tokens are generated at runtime and are scoped to the task that generated them. Tokens can be generated with Airplane's SDKs or they can be configured within a task or resource definition.

Your token must be associated with an audience which identifies the intended recipient of the token. The audience is provided as a parameter when generating the token. If the audience is incorrect, the consumer will reject the token. (For AWS, this audience is sts.amazonaws.com. For your own APIs, you can specify an audience such as auth.yourcompany.com.)

If you are using a JavaScript or Python task, you can use the Airplane SDK to generate tokens. For other tasks like REST or shell, you should, you should use the auth.idToken(aud) JST in your task configuration to generate tokens.

JST configuration can also be used to configure resources if you want to always attach tokens when using those resources. For example, this can be used to always include the token as a header for a REST resource or a GraphQL resource.

SDKs

Tokens can be generated at runtime with Airplane's SDKs. For example, to generate an OIDC token with audience sts.amazonaws.com to assume an AWS role:

typescript
Copied
1
import { STSClient } from "@aws-sdk/client-sts";
2
import { AssumeRoleWithWebIdentityCommand } from "@aws-sdk/client-sts";
3
import airplane from "airplane";
4

5
export default airplane.task(
6
  {
7
    slug: "test_oidc_aws",
8
  },
9
  async (params) => {
10
    const token = await airplane.auth.idToken("sts.amazonaws.com");
11

12
    const command = new AssumeRoleWithWebIdentityCommand({
13
      RoleArn: "arn:aws:iam::000000000000:role/my_aws_role",
14
      WebIdentityToken: token,
15
      RoleSessionName: "my_session",
16
    });
17

18
    const client = new STSClient({ region: "us-east-1" });
19
    console.log(await client.send(command));
20
  },
21
);

Resources and task definitions

Tokens can be configured within a resource or task via JS Templates. The auth.idToken(aud) function is provided as a resource global and a task global.

Set token as a REST resource header

You may want to configure a REST resource so that a token is included in all requests.

Set token as an environment variable for a shell task

YAML-based tasks such as shell and REST tasks can generate tokens via JSTs.

yaml
Copied
1
slug: shell_oidc_example
2
name: Shell OIDC Example
3
envVars:
4
  ID_TOKEN:
5
    value: "{{auth.idToken('sts.amazonaws.com')}}"
6
shell:
7
  # my_task.sh can access it as $ID_TOKEN
8
  entrypoint: my_task.sh

Token payload reference

OIDC tokens generated by Airplane's OIDC provider are signed JSON web tokens (JWTs). The ID token is encoded by using RS256 and signed with a dedicated private key. The expiry time for the token is set for 48 hours.

The token includes the standard audience, issuer, and subject claims.

Claim	Description
`aud`	Intended audience for the token. This field is set by the user when fetching the ID token and is the only customizable field.
`iss`	The issuer of the token, https://api.airplane.dev
`sub`	The subject claim is validated by your cloud provider. The subject is formatted as `team:{$team_id}:env:{$env_slug}:task:{$task_slug}`. If the token was generated in Studio, the `env_slug` value will be `studio`.

The token also includes custom claims provided by Airplane. To see the full list of claims supported by Airplane's OIDC provider, see the claims_supported entries at https://api.airplane.dev/.well-known/openid-configuration.

Tokens generated locally in Studio will have the environment slug studio in its claims. Take this into consideration when configuring your authentication rules. You may want to limit permissions for locally generated tokens.

Claim	Description
`run_id`	The ID of the run that generated the token.
`parent_run_id`	If the run was triggered by another run, contains the ID of the parent run.
`env_id`	The ID of the environment the token was generated in. If the token was generated in Studio, the `env_id` value will be `studio`.
`env_slug`	The slug of the environment the token was generated in. If the token was generated in Studio, the `env_slug` value will be `studio`.
`requester_id`	If the run was requested, contains the ID of the user that requested the run.
`requester_email`	If the run was requested, contains the email of the user that requested the run.
`requester_groups`	If the run was requested, a list of the group slugs that the requester belongs to.
`runner_id`	The ID of the user that executed the run.
`runner_email`	The email of the user that executed the run.
`runner_groups`	A list of the group slugs the user belongs to.
`task_id`	The ID of the task that generated the token.
`task_slug`	The slug of the task that generated the token.
`team_id`	The ID of the team that generated the token.
`trigger_id`	The ID of the trigger that created the run.

The token also has additional standard claims.

Claim	Description
`exp`	The expiration time of the token.
`iat`	The time the token was issued.
`alg`	The algorithm used to sign the token.
`kid`	The key ID used to sign the token.

The following example token was requested with the audience sts.amazonaws.com from the task test_oidc_aws in the prod environment:

json
Copied
1
{
2
  "alg": "RS256",
3
  "kid": "616972706c616e652d6f696463"
4
}
5
{
6
  "aud": ["sts.amazonaws.com"],
7
  "env_id": "env20010101aaaaaaaaaa",
8
  "env_slug": "prod",
9
  "exp": 1681905231,
10
  "iat": 1681840431,
11
  "iss": "https://api.airplane.dev",
12
  "parent_run_id": "",
13
  "requester_email": "",
14
  "requester_id": "",
15
  "run_id": "run20010101aaaaaaaaaa",
16
  "runner_email": "test@airplane.dev",
17
  "runner_id": "usr20010101aaaaaaaaaa",
18
  "runner_groups": ["admins", "devs"],
19
  "sub": "team:tea20010101aaaaaaaaaa:env:prod:task:test_oidc_aws",
20
  "task_id": "tsk20010101aaaaaaaaaa",
21
  "task_slug": "test_oidc_aws",
22
  "team_id": "tea20010101aaaaaaaaaa",
23
  "trigger_id": "trg20010101aaaaaaaaaa"
24
}

Settings discovery

Airplane's OIDC settings are available at the following discovery URL:


Copied
1
https://airplane.dev/.well-known/openid-configuration

SDK reference

See Auth SDK reference for more information.