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:typescriptCopied1import { STSClient } from "@aws-sdk/client-sts";2import { AssumeRoleWithWebIdentityCommand } from "@aws-sdk/client-sts";3import airplane from "airplane";45export default airplane.task(6{7slug: "test_oidc_aws",8},9async (params) => {10const token = await airplane.auth.idToken("sts.amazonaws.com");1112const command = new AssumeRoleWithWebIdentityCommand({13RoleArn: "arn:aws:iam::000000000000:role/my_aws_role",14WebIdentityToken: token,15RoleSessionName: "my_session",16});1718const client = new STSClient({ region: "us-east-1" });19console.log(await client.send(command));20}21);
javascriptCopied1import { STSClient } from "@aws-sdk/client-sts";2import { AssumeRoleWithWebIdentityCommand } from "@aws-sdk/client-sts";3import airplane from "airplane";45export default airplane.task(6{7slug: "test_oidc_aws",8},9async (params) => {10const token = await airplane.auth.idToken("sts.amazonaws.com");1112const command = new AssumeRoleWithWebIdentityCommand({13RoleArn: "arn:aws:iam::000000000000:role/my_aws_role",14WebIdentityToken: token,15RoleSessionName: "my_session",16});1718const client = new STSClient({ region: "us-east-1" });19console.log(await client.send(command));20}21);
pythonCopied1import airplane2import boto334@airplane.task()5def test_oidc_aws():6sts = boto3.client("sts")78token = airplane.auth.id_token("sts.amazonaws.com")910credentials = sts.assume_role_with_web_identity(11RoleArn="arn:aws:iam::000000000000:role/my_aws_role",12WebIdentityToken=token,13RoleSessionName="my_session",14)15print(credentials)
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.
yamlCopied1slug: shell_oidc_example2name: Shell OIDC Example3envVars:4ID_TOKEN:5value: "{{auth.idToken('sts.amazonaws.com')}}"6shell:7# my_task.sh can access it as $ID_TOKEN8entrypoint: 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. |
runner_id | The ID of the user that executed the run. |
runner_email | The email of the user that executed the run. |
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:jsonCopied1{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"sub": "team:tea20010101aaaaaaaaaa:env:prod:task:test_oidc_aws",19"task_id": "tsk20010101aaaaaaaaaa",20"task_slug": "test_oidc_aws",21"team_id": "tea20010101aaaaaaaaaa",22"trigger_id": "trg20010101aaaaaaaaaa"23}
Settings discovery
Airplane's OIDC settings are available at the following discovery URL:
Copied1https://airplane.dev/.well-known/openid-configuration