DNAnexus Documentation
APIDownloadsIndex of dx CommandsLegal
  • Overview
  • Getting Started
    • DNAnexus Essentials
    • Key Concepts
      • Projects
      • Organizations
      • Apps and Workflows
    • User Interface Quickstart
    • Command Line Quickstart
    • Developer Quickstart
    • Developer Tutorials
      • Bash
        • Bash Helpers
        • Distributed by Chr (sh)
        • Distributed by Region (sh)
        • SAMtools count
        • TensorBoard Example Web App
        • Git Dependency
        • Mkfifo and dx cat
        • Parallel by Region (sh)
        • Parallel xargs by Chr
        • Precompiled Binary
        • R Shiny Example Web App
      • Python
        • Dash Example Web App
        • Distributed by Region (py)
        • Parallel by Chr (py)
        • Parallel by Region (py)
        • Pysam
      • Web App(let) Tutorials
        • Dash Example Web App
        • TensorBoard Example Web App
      • Concurrent Computing Tutorials
        • Distributed
          • Distributed by Region (sh)
          • Distributed by Chr (sh)
          • Distributed by Region (py)
        • Parallel
          • Parallel by Chr (py)
          • Parallel by Region (py)
          • Parallel by Region (sh)
          • Parallel xargs by Chr
  • User
    • Login and Logout
    • Projects
      • Project Navigation
      • Path Resolution
    • Running Apps and Workflows
      • Running Apps and Applets
      • Running Workflows
      • Running Nextflow Pipelines
      • Running Batch Jobs
      • Monitoring Executions
      • Job Notifications
      • Job Lifecycle
      • Executions and Time Limits
      • Executions and Cost and Spending Limits
      • Smart Reuse (Job Reuse)
      • Apps and Workflows Glossary
      • Tools List
    • Cohort Browser
      • Chart Types
        • Row Chart
        • Histogram
        • Box Plot
        • List View
        • Grouped Box Plot
        • Stacked Row Chart
        • Scatter Plot
        • Kaplan-Meier Survival Curve
      • Locus Details Page
    • Using DXJupyterLab
      • DXJupyterLab Quickstart
      • Running DXJupyterLab
        • FreeSurfer in DXJupyterLab
      • Spark Cluster-Enabled DXJupyterLab
        • Exploring and Querying Datasets
      • Stata in DXJupyterLab
      • Running Older Versions of DXJupyterLab
      • DXJupyterLab Reference
    • Using Spark
      • Apollo Apps
      • Connect to Thrift
      • Example Applications
        • CSV Loader
        • SQL Runner
        • VCF Loader
      • VCF Preprocessing
    • Environment Variables
    • Objects
      • Describing Data Objects
      • Searching Data Objects
      • Visualizing Data
      • Filtering Objects and Jobs
      • Archiving Files
      • Relational Database Clusters
      • Symlinks
      • Uploading and Downloading Files
        • Small File Sets
          • dx upload
          • dx download
        • Batch
          • Upload Agent
          • Download Agent
    • Platform IDs
    • Organization Member Guide
    • Index of dx commands
  • Developer
    • Developing Portable Pipelines
      • dxCompiler
    • Cloud Workstation
    • Apps
      • Introduction to Building Apps
      • App Build Process
      • Advanced Applet Tutorial
      • Bash Apps
      • Python Apps
      • Spark Apps
        • Table Exporter
        • DX Spark Submit Utility
      • HTTPS Apps
        • Isolated Browsing for HTTPS Apps
      • Transitioning from Applets to Apps
      • Third Party and Community Apps
        • Community App Guidelines
        • Third Party App Style Guide
        • Third Party App Publishing Checklist
      • App Metadata
      • App Permissions
      • App Execution Environment
        • Connecting to Jobs
      • Dependency Management
        • Asset Build Process
        • Docker Images
        • Python package installation in Ubuntu 24.04 AEE
      • Job Identity Tokens for Access to Clouds and Third-Party Services
      • Enabling Web Application Users to Log In with DNAnexus Credentials
      • Types of Errors
    • Workflows
      • Importing Workflows
      • Introduction to Building Workflows
      • Building and Running Workflows
      • Workflow Build Process
      • Versioning and Publishing Global Workflows
      • Workflow Metadata
    • Ingesting Data
      • Molecular Expression Assay Loader
        • Common Errors
        • Example Usage
        • Example Input
      • Data Model Loader
        • Data Ingestion Key Steps
        • Ingestion Data Types
        • Data Files Used by the Data Model Loader
        • Troubleshooting
      • Dataset Extender
        • Using Dataset Extender
    • Dataset Management
      • Rebase Cohorts and Dashboards
      • Assay Dataset Merger
      • Clinical Dataset Merger
    • Apollo Datasets
      • Dataset Versions
      • Cohorts
    • Creating Custom Viewers
    • Client Libraries
      • Support for Python 3
    • Walkthroughs
      • Creating a Mixed Phenotypic Assay Dataset
      • Guide for Ingesting a Simple Four Table Dataset
    • DNAnexus API
      • Entity IDs
      • Protocols
      • Authentication
      • Regions
      • Nonces
      • Users
      • Organizations
      • OIDC Clients
      • Data Containers
        • Folders and Deletion
        • Cloning
        • Project API Methods
        • Project Permissions and Sharing
      • Data Object Lifecycle
        • Types
        • Object Details
        • Visibility
      • Data Object Metadata
        • Name
        • Properties
        • Tags
      • Data Object Classes
        • Records
        • Files
        • Databases
        • Drives
        • DBClusters
      • Running Analyses
        • I/O and Run Specifications
        • Instance Types
        • Job Input and Output
        • Applets and Entry Points
        • Apps
        • Workflows and Analyses
        • Global Workflows
        • Containers for Execution
      • Search
      • System Methods
      • Directory of API Methods
      • DNAnexus Service Limits
  • Administrator
    • Billing
    • Org Management
    • Single Sign-On
    • Audit Trail
    • Integrating with External Services
    • Portal Setup
    • GxP
      • Controlled Tool Access (allowed executables)
  • Science Corner
    • Scientific Guides
      • Somatic Small Variant and CNV Discovery Workflow Walkthrough
      • SAIGE GWAS Walkthrough
      • LocusZoom DNAnexus App
      • Human Reference Genomes
    • Using Hail to Analyze Genomic Data
    • Open-Source Tools by DNAnexus Scientists
    • Using IGV Locally with DNAnexus
  • Downloads
  • FAQs
    • EOL Documentation
      • Python 3 Support and Python 2 End of Life (EOL)
    • Automating Analysis Workflow
    • Backups of Customer Data
    • Developing Apps and Applets
    • Importing Data
    • Platform Uptime
    • Legal and Compliance
    • Sharing and Collaboration
    • Product Version Numbering
  • Release Notes
  • Technical Support
  • Legal
Powered by GitBook

Copyright 2025 DNAnexus

On this page
  • Setup
  • Step 1. Establish Trust Between the Platform and Your Cloud Provider
  • Step 2. Configure Trust Conditions and Access Permissions
  • Using Job Identity Tokens from Inside Your Jobs
  • Step 1. Obtain a Job Identity Token
  • Step 2. Exchange a Token for Cloud Access Credentials

Was this helpful?

Export as PDF
  1. Developer
  2. Apps

Job Identity Tokens for Access to Clouds and Third-Party Services

Learn how to use job identity tokens to enable jobs to access external services such as your AWS cloud resources.

Last updated 8 months ago

Was this helpful?

Job identity tokens are DNAnexus-signed that establish a security-hardened and verifiable identity linked to a DNAnexus job. Many third party systems, including cloud providers such as Amazon Web Services, Microsoft Azure, and Google Cloud, can receive and validate these tokens, and exchange them for temporary cloud access credentials. A job can then use those credentials to access approved resources in those systems. This modern approach, based on interoperable standards (OpenID Connect tokens), avoids the burden of distributing and rotating long-lived cloud secrets, and allows customers to leverage their cloud provider's authentication and authorization tools to determine, on a granular level, which DNAnexus jobs can access what third-party cloud resources.

App authors can use this feature to provide secure access to the specific external resources required by each job. These can include storage buckets, serverless functions, databases, and secrets vaults. In addition, this feature can be used to access any systems that support this type of JWT authentication, such as Salesforce, Oracle API Gateway, and HashiCorp Vault.

Setup

Step 1. Establish Trust Between the Platform and Your Cloud Provider

As a first step, you must establish trust between the DNAnexus Platform, as an OIDC identity provider, and the cloud service provider whose system your jobs will need to access.

Each cloud provider will have its own procedure for establishing trust. For AWS, consult, using the following parameters:

  • For "Provider URL", enter

  • For "Audience", enter any string (consisting of lowercase or uppercase letters, numbers, and the symbols ., _ or -) that describes your use case. The value you provide is what AWS will expect to encounter in job identity tokens generated by DNAnexus. So this value must match the value the value of .

Note: When using trust conditions (recommended), the value of audience does not need to be protected as a secret but it should remain private and accessible only to authorized workloads.

Step 2. Configure Trust Conditions and Access Permissions

Next you need to define which jobs are allowed to request access credentials, by configuring trust conditions within your cloud provider's system. These are conditions that must be met before your cloud provider can exchange job identity tokens for credentials.

In addition, you need to define what resources - what cloud storage buckets, for example, or what other cloud services - can be accessed by jobs using the access credentials returned by the token exchange. To do this, you must configure access permissions within your cloud provider's system.

Each cloud provider has a different mechanism for configuring trust conditions and access permissions. On AWS, you must create a role and attach a trust policy (for trust conditions) and a permissions policy (for access permissions). For more information, see .

Specifying Trust Conditions

When configuring trust conditions, most clouds allow you to specify rules based on token claims.

Token claims are system fields, included in job identity tokens, that contain metadata about the job. For example, the token claim "launched_by" contains the username of the user who launched the job, while the token claim "project_id" contains the ID of the project in which the job is running. When setting up trust conditions on your cloud provider, you can specify rules such as "project_id must match project-12345" so that your cloud provider will only trust jobs running in that project.

Job identity tokens issued by DNAnexus include a list of standard claims mandated by the OIDC and JWT specifications, as well as a list of custom DNAnexus-specific claims that capture job metadata.

The standard claims are as follows:

Claim

Claim Type

Description

aud

Audience

A user-provided string denoting the audience that this token is intended for. This is typically expected to match the audience as configured in the third party system.

iss

Issuer

Always set to https://job-oidc.dnanexus.com.

sub

Subject

A "subject" string which is assembled by concatenating user-chosen job metadata. By default this concatenates the launched_by and job_worker_ipv4 metadata.

exp

Expires at

The time (in seconds from epoch) when this token expires. This is always set to 5 minutes after the issuing time.

iat

Issued at

The time (in seconds from epoch) when this token was issued.

jti

JWT token Identifier

A unique identifier for this token.

nbf

Not before

The time (in seconds from epoch) when this token will start being valid. This is always set to the same time as the issuing time.

The additional DNAnexus-specific claims are as follows:

Claim

Example Value

Meaning

job_id

job-xxxx

The id of the job that requested the identity token.

root_execution_id

analysis-xxxx,

job-xxxx

The id of the top-level execution (analysis or job) that this job is part of.

root_executable_id

applet-xxxx, workflow-xxxx, app-xxxx,

globalworkflow-xxxx

The id of the top-level executable (applet, workflow, app, or globalworkflow).

root_executable_name

app-foo,

globalworfklow-bar

The (prefixed with "app-" or "globalworfklow-") name of the root executable, populated ONLY when the root executable is an app or globalworkflow.

root_executable_version

1.2.3

The version identifier of the root executable, populated ONLY when the root executable is an app or globalworkflow

executable_id

applet-xxxx,

app-xxxx

The id of the app or applet that this job is running.

app_name

app-foo

The (prefixed with "app-") name of the executable, populated ONLY when the executable is an app.

app_version

1.2.3

The version identifier of the executable, populated ONLY when the executable is an app

project_id

project-xxxx

The project id of the job.

bill_to

org-customer,

user-selfbilled

The billTo of the job. Note that project billTos can change while jobs are still running. This field reflect's the job's billTo which does not change (i.e. reflects what the historic billTo of the job was at the time the root execution was created).

launched_by

user-alice

The user entity that launched the job.

region

aws:eu-west-2-g

The region of the project in which the job is running.

job_worker_ipv4

1.2.3.4

The IPv4 address as it appears to third parties, when this job initiates a connection to any Internet endpoint – which as of today equals the outbound public IPv4 interface of the VM where the job is running. (For cluster jobs, this IP reflects each VM separately).

job_try

0

The try (attempt) of the job that requested the identity token.

kid

f47790d10

The unique key identifier for the identity token.

The following table summarizes some examples of how token claims can be leveraged to implement specific helpful conditions.

Goal
Conditions*

Only jobs launched by user-alice

launched_by = user-alice

Only jobs running in project-123

project_id = project-123

Only jobs running in projects billed to org-x

bill_to = org-x

Only jobs that are directly running as part of app-abc

app_name = app-abc

All jobs from any step of globalworkflow-xyz

root_executable_name = globalworkflow-xyz

* The exact syntax for trust conditions varies across cloud providers.

Using Job Identity Tokens from Inside Your Jobs

For a job to access cloud resources at runtime, it must first obtain a job identity token, then present it to a cloud service, in exchange for temporary cloud access credentials.

Step 1. Obtain a Job Identity Token

You can optionally adjust the subject ("sub") claim of the resulting token using the --subject_claims parameter. The subject claim is assembled by concatenating user-chosen job metadata.

  • The default is --subject_claims launched_by --subject_claims job_worker_ipv4, resulting in a subject that looks like this:

    launched_by;user-alice;job_worker_ipv4;1.2.3.4

  • To select other metadata to concatenate, specify them in one or more --subject_claims parameters. For example, using --subject_claims job_id --subject_claims job_try will result in a subject that looks like this: job_id;job-1234;job_try;0

Depending on your cloud provider, the subject ("sub") claim may have unique significance. On AWS, the subject claim propagates as a context key (job-oidc.dnanexus.com:sub) in exchanged credentials when evaluating subsequent permission policies. This allows you to leverage its contents when specifying access permissions rules. (Token claims are otherwise limited to trust conditions rules, not access permission rules).

Step 2. Exchange a Token for Cloud Access Credentials

Your script must incorporate cloud provider-specific code that allows for the exchange of the signed JWT for cloud access credentials. Then it must use those credentials to access the cloud service provider's system.

To do this on AWS:

    • AWS_ACCESS_KEY_ID

    • AWS_SECRET_ACCESS_KEY

    • AWS_SESSION_TOKEN

To obtain a job identity token at runtime, your job must execute the command , then save its output, which will be used in the next step.

To run this command, you must specify an audience, exactly as you want it to appear in the "aud" claim of the resulting token, using the --aud parameter. Later, when your job presents this token to a cloud provider, most cloud providers expect the audience to match whatever was used when .

Use this command to exchange the signed JWT (from Step 1 above) for a short-lived STS token: aws sts assume-role-with-web-identity --web-identity-token <signed JWT token> --role-arn <arn of IAM role from AWS account> --duration-seconds 900 See .

The output of the command above will be a JSON response with a "Credentials" hash. Use values from that hash to set the following , in order to access AWS resources:

this AWS documentation for detailed guidance
environment variables
originally configuring trust on the cloud provider's system
JSON Web Tokens (JWT)
this guide
https://job-oidc.dnanexus.com
this AWS guide
"--aud" that is provided to dx-jobutil-get-identity-token
dx-jobutil-get-identity-token