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:

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.
ClaimDescription
audIntended audience for the token. This field is set by the user when fetching the ID token and is the only customizable field.
issThe issuer of the token, https://api.airplane.dev
subThe 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.
ClaimDescription
run_idThe ID of the run that generated the token.
parent_run_idIf the run was triggered by another run, contains the ID of the parent run.
env_idThe ID of the environment the token was generated in. If the token was generated in Studio, the env_id value will be studio.
env_slugThe slug of the environment the token was generated in. If the token was generated in Studio, the env_slug value will be studio.
requester_idIf the run was requested, contains the ID of the user that requested the run.
requester_emailIf the run was requested, contains the email of the user that requested the run.
requester_groupsIf the run was requested, a list of the group slugs that the requester belongs to.
runner_idThe ID of the user that executed the run.
runner_emailThe email of the user that executed the run.
runner_groupsA list of the group slugs the user belongs to.
task_idThe ID of the task that generated the token.
task_slugThe slug of the task that generated the token.
team_idThe ID of the team that generated the token.
trigger_idThe ID of the trigger that created the run.
The token also has additional standard claims.
ClaimDescription
expThe expiration time of the token.
iatThe time the token was issued.
algThe algorithm used to sign the token.
kidThe 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.