@veraid/authority-credentials

JS library to automate the exchange of cloud credentials for VeraId credentials via VeraId Authority.

Installation

This library is available on NPM as @veraid/authority-credentials.

Usage

To use any of the built-in integrations and have them auto-configure themselves (e.g. from environment variables), use initExchangerFromEnv as follows:

import { initExchangerFromEnv } from '@veraid/authority-credentials';

// Replace with the actual URL for exchanging credentials
const EXCHANGE_ENDPOINT = new URL('https://veraid-authority.example/credentials/123');

// Replace with the exchanger you want to use
const EXCHANGER_NAME = 'GITHUB';

const exchanger = initExchangerFromEnv(EXCHANGER_NAME);
const { credential } = await exchanger.exchange(EXCHANGE_ENDPOINT);

Alternatively, you can use the specific integration class directly.

Built-in Integrations

GitHub (GITHUB)

GithubExchanger can be used to exchange GitHub tokens for VeraId credentials as follows:

import { GithubExchanger } from '@veraid/authority-credentials';

// Replace with the actual URL for exchanging credentials
const EXCHANGE_ENDPOINT = new URL('https://veraid-authority.example/credentials/123');

const exchanger = GithubExchanger.initFromEnv();
const { credential } = await exchanger.exchange(EXCHANGE_ENDPOINT);

When configured from environment variables, ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN must be set. They're automatically set when the GitHub job has been granted the id-token: write permission. Learn more on the GitHub documentation.

Amazon Web Services

AWS doesn't appear to offer a passwordless way for a workflow to obtain JWTs from Amazon Cognito, so AWS will be supported via OAuth2 Client Credentials.

Google Cloud Platform

Google Cloud Platform support is on the roadmap.

Kubernetes

Kubernetes support is on the roadmap.

Microsoft Azure

Azure support is on the roadmap.

OAuth2 Client Credentials

OAuth2 Client Credentials support is on the roadmap.

Custom Integrations

You can create a custom integration by extending the JwtExchanger class.

API docs

The API documentation can be found on docs.veraid.net.

Contributions

We love contributions! If you haven't contributed to a Relaycorp project before, please take a minute to read our guidelines first.

Issues are tracked on the VAUTH project on Jira (Credentials Exchanger (JS) component).