Search the documentation
Search the documentation...
SplitSecure documentation

On this page

Procedure · 11 steps

Set up service accounts

Give a machine its own identity in your organization, and let it sign in with a key or with its CI token.

Updated

Before you start

A service account is a member of your organization that is a machine, such as a continuous integration (CI) job or a Terraform run. It has a role like a person, takes no seat, and can sign in two ways:

  • With a key: you register the public half of a key pair, and the machine signs with the private half.
  • With workload identity: the machine presents the token its platform already gives it, such as a GitHub Actions token, and a binding says which tokens may act as the account. There is no key to store or rotate.

An organization holds up to 5 service accounts.

Create the service account

In the Web App

  1. In the sidebar, click Organization → Advanced → Service accounts.
  2. Click Create service account.
  3. Enter the Name, for example ci-bot. Use lowercase letters, digits, dots, dashes and underscores.
  4. Click Create.

The account’s page opens. Its Email is the account’s address in SplitSecure. It receives no mail.

The account starts as a Member. To let it manage groups or reach every resource, for example for Terraform:

  1. In the page header, open the role menu.
  2. Choose Admin or Auditor.

An Admin service account can change everything an Admin can. Give it that role only when it needs it.

Sign in with a key

In the Web App

An account holds up to 2 keys, enough to rotate one. Keys do not expire.

  1. On the account’s page, under Signing keys, click Register key.

  2. Enter a Name, for example CI runner.

  3. Under How, choose one.

    How What you do
    Generate in browser Pick an Algorithm, click Generate keypair, then save the private key it shows
    Paste a public key Paste a PEM block or a JSON Web Key (JWK). The page shows the openssl commands that make one
    Import from a file Pick the public key file. A file holding a private key is refused
  4. With Generate in browser, check I saved the private key.

  5. Click Register.

The algorithms are ECDSA P-256, P-384 and P-521, and Ed25519.

The machine signs a JSON Web Token (JWT) assertion with the private key, naming the key ID in its header and the service account as both iss and sub.

  1. Register the new key, and switch the machine to it.
  2. Click the old key’s row, then Delete, then Delete in the confirmation.

Anything that signs with a deleted key stops working at once.

Sign in with workload identity

In the Web App

A binding lets one subject of a trusted token issuer act as the account. These issuers are built in:

Provider Issuer
GitHub Actions https://token.actions.githubusercontent.com
GitLab Your GitLab host, gitlab.com by default
CircleCI Your CircleCI organization
Google Cloud https://accounts.google.com
HCP Terraform https://app.terraform.io
Buildkite https://agent.buildkite.com

Skip this step for a built-in issuer.

  1. In the sidebar, click Organization → Advanced → Workload identity.

  2. Click Add a custom identity provider.

  3. Fill in the fields.

    Field Value
    Name A name for the issuer
    Issuer URL The iss its tokens carryIt must start with https://
    Keys Fetch them from a URL or Paste a JWK SetUse the pasted set only when the issuer publishes no keys URL
    Audience The aud its tokens must carry
  4. Click Add.

An organization holds up to 20 custom issuers.

  1. On the service account’s page, under Identity bindings, click Add binding.

  2. Fill in the fields.

    Field Value
    Identity provider The issuerSome ask for a value, such as the GitLab host or the CircleCI organization ID
    Name A name for the bindingFor example Deploy job
    Subject The token’s subMatch it Is exactly, Starts with or Matches the pattern. Enter a sample under Try a value to test the match
    Claim rules Optional, up to 8Every rule must match, for example repository is acme/api
  3. Note the audience the page shows: the machine’s token must carry it.

  4. Click Add.

An account holds up to 20 bindings. You can edit a binding’s name, subject and claim rules, but not its issuer.

Call SplitSecure from the machine

The machine trades its credential for a token, then calls the API with it. Every request goes to https://monolith.us-east-2.us.splitsecure.com, written https://<host> below. Each one carries a DPoP proof (Demonstrating Proof of Possession), a short JWT that shows the caller holds a key.

In your code

  1. Generate one ECDSA P-256 key pair for the session, separate from the service account’s key.
  2. Use it to sign every DPoP proof below. All three requests must use the same DPoP key.

Each proof is a JWT signed with ES256:

Field Value
typ dpop+jwtIn the header
jwk The DPoP public key, as an EC JWKIn the header
htm POSTThe request’s method
htu The request’s full URL, without a queryFor example https://<host>/authn/exchange
iat The current timeAt most 60 seconds old
jti A unique ID
ath The SHA-256 of the service token, base64urlOn API calls only
  1. Send POST /authn/exchange, form encoded, with the proof in a DPoP header.

With a key, send these fields:

Field Value
grant_type urn:ietf:params:oauth:grant-type:jwt-bearer
assertion The JWT signed with the service account’s keyIts claims are listed below
audience The SplitSecure host, as https://<host> No path and no trailing slash

The assertion’s header carries alg, the key’s algorithm, and kid, the Key ID. Its claims are:

Field Value
iss The Assertion subjectThe service account’s ID
sub The Assertion subjectThe same value as iss
aud https://<host>/authn/exchange
iat The current time
exp At most 5 minutes after iat
jti A unique ID, 8 to 128 charactersEach assertion is accepted once

With workload identity, send these fields:

Field Value
grant_type urn:ietf:params:oauth:grant-type:token-exchange
subject_token The token your platform issuedIt must carry the audience the binding page shows
subject_token_type urn:ietf:params:oauth:token-type:jwt
service_account The service account’s IDThe Assertion subject on a key, or the account’s page
audience The SplitSecure host, as https://<host> No path and no trailing slash

The answer holds an access_token, the identity token, valid for 5 minutes.

  1. Send POST /servicetoken/exchange, form encoded, with a new proof in a DPoP header.
Field Value
grant_type urn:ietf:params:oauth:grant-type:token-exchange
subject_token The identity tokenEach one is accepted once
subject_token_type urn:ietf:params:oauth:token-type:jwt

The answer holds an access_token that starts with s2st_, valid for 15 minutes. There is no refresh token: when it expires, get a new identity token, then a new service token.

  1. Send each API request with two headers: Authorization: Bearer followed by the service token, and DPoP with a new proof that includes ath.

The scheme is Bearer, even though the token’s token_type reads DPoP.

Delete a service account

In the Web App

  1. On the account’s page, under Delete this service account, click Delete service account.
  2. Click Delete.

Its keys and bindings are deleted with it, and stop working at once.

Troubleshooting

Issue Solution
This organization has reached its limit of 5 service accounts. The organization holds 5 accountsDelete one you no longer use
This service account has reached its limit of 2 keys. The account holds 2 keysDelete the old key
This file holds a private key. Import the public half instead. The file is a private keyImport the public key file
A service account still binds to this identity provider. A binding uses the custom issuer you are deletingDelete those bindings first
The machine gets invalid_grant The token’s issuer, audience, subject or claims do not matchCompare the token’s claims with the binding
invalid_dpop_proof The DPoP proof is missing, signed with another key, or older than 60 secondsSign a new proof for each request with the same P-256 key
invalid_grant on /servicetoken/exchange The identity token expired, was already used, or names another audienceGet a new identity token. Send the host exactly as https://<host>
unrecognized bearer token format on an API call The Authorization header does not start with BearerSend Authorization: Bearer followed by the service token
The machine gets Service accounts are not available on this organization’s plan. Your plan does not include service accountsMove to a plan (opens in a new tab) that includes them

External resources