@electron/circleci-oidc-secret-exchange
v1.7.0
Published
Provides dynamic access to secrets in exchange for a valid OIDC token
Downloads
120
Readme
@electron/circleci-oidc-secret-exchange
Provides dynamic access to secrets in exchange for a valid OIDC token
Usage
import { configureAndListen } from '@electron/circleci-oidc-secret-exchange';
configureAndListen([
{
organizationId: 'foo',
secrets: [ ... ],
},
{
organizationId: 'bar',
secrets: [ ... ]
}
])
By default configureAndListen
listens on $PORT
for incoming requests. In CircleCI you just need to POST a valid OIDC token to the
/exchange
endpoint. You'll receive a JSON key<>value map of secrets for your build job.
Secret Providers
All secret providers are configured with a filters
object which dictates which CircleCI projects and contexts are allowed access
to the secrets it provides. Please note that we apply an and operation to the projectIds
and contextIds
filters. So the
OIDC token must be issued for an allowed project and an allowed context. Not just one or the other.
// Will only use this provider if the OIDC token is generated for project abc-def and the build is running in context 123-456
{
provider: () => ...,
filters: {
projectIds: ['abc-def'],
contextIds: ['123-456'],
}
}
We have a few built-in secret providers documented below, you can build your own provider by importing and implementing the base SecretProvider
class.
Generic Secret Provider
This provider allows you to load secrets from anywhere and hand them back in key<>value form.
import { GenericSecretProvider } from '@electron/circleci-oidc-secret-exchange';
export const config = [
{
organizationId: 'foo',
secrets: [
provider: () => new GenericSecretProvider(
async () => ({
MY_COOL_SECRET: process.env.MY_COOL_SECRET,
OTHER_SECRET: await getFromSomewhere(),
})
),
filters: { ... },
]
}
]
File Secret Provider
This provider loads a JSON file from disk and let's you read and provide secrets from it. The file is read fresh on every request so if you change the file on disk even without restarting the service the updated secrets will be read
import { FileSecretProvider } from '@electron/circleci-oidc-secret-exchange';
export const config = [
{
organizationId: 'foo',
secrets: [
provider: () => new FileSecretProvider('/etc/org.d/secrets.json', (secrets) => ({
MY_SECRET_KEY: secrets.fooSecret,
OTHER_SECRET_KEY: secrets.barSecret,
})),
filters: { ... },
]
}
]
GitHub App Token Provider
This provider hands off a permission-scoped, repo-scoped GitHub App installation token as a secret. These tokens last ~60 minutes so you if your job takes longer than that the token will no longer be valid.
To generate the credentials bundle for credsString
, see the instructions on electron/github-app-auth
.
import { GitHubAppTokenProvider } from '@electron/circleci-oidc-secret-exchange';
export const config = [
{
organizationId: 'foo',
secrets: [
provider: () => new GitHubAppTokenProvider({
// Creds bundle generated for `@electron/github-app-auth`
credsString: process.env.MY_GITHUB_APP_CREDS,
// The repo to generate this token for, could be any repo
// not just the repo that generated the OIDC token
repo: {
owner: 'my-org',
name: 'my-repo',
},
// A key<>value map of GitHub app permissions and their values
permissions: {
members: 'read',
contents: 'write',
}
}),
filters: { ... },
]
}
]
By default the GitHubAppTokenProvider
provides a secret with the name GITHUB_TOKEN
. You can change that name by providing it as a second parameter to the constructor.