Before you start
- An Owner or Admin role in the organization.
- A plan (opens in a new tab) that includes service accounts.
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
- In the sidebar, click Organization → Advanced → Service accounts.
- Click Create service account.
- Enter the Name, for example
ci-bot. Use lowercase letters, digits, dots, dashes and underscores. - 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:
- In the page header, open the role menu.
- 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.
On the account’s page, under Signing keys, click Register key.
Enter a Name, for example
CI runner.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 opensslcommands that make oneImport from a file Pick the public key file. A file holding a private key is refused With Generate in browser, check I saved the private key.
Click Register.
The algorithms are ECDSA P-256, P-384 and P-521, and Ed25519.
SplitSecure never stores the private key. A key generated in the browser is shown once, and is gone when you leave the page.
The key is registered shows the Key ID, the Algorithm and the Assertion subject.
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.
- Register the new key, and switch the machine to it.
- 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.
In the sidebar, click Organization → Advanced → Workload identity.
Click Add a custom identity provider.
Fill in the fields.
Field Value Name A name for the issuer Issuer URL The issits tokens carryIt must start withhttps://Keys Fetch them from a URL or Paste a JWK SetUse the pasted set only when the issuer publishes no keys URL Audience The audits tokens must carryClick Add.
An organization holds up to 20 custom issuers.
On the service account’s page, under Identity bindings, click Add binding.
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 jobSubject The token’s subMatch it Is exactly, Starts with or Matches the pattern. Enter a sample under Try a value to test the matchClaim rules Optional, up to 8Every rule must match, for example repositoryisacme/apiNote the audience the page shows: the machine’s token must carry it.
Click Add.
An account holds up to 20 bindings. You can edit a binding’s name, subject and claim rules, but not its issuer.
A loose subject lets more workloads act as the account. For GitHub Actions, match the repository and the branch, such as repo:acme/api:ref:refs/heads/main, rather than a prefix of the owner.
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
- Generate one ECDSA P-256 key pair for the session, separate from the service account’s key.
- 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 |
- Send
POST /authn/exchange, form encoded, with the proof in aDPoPheader.
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.
- Send
POST /servicetoken/exchange, form encoded, with a new proof in aDPoPheader.
| 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.
- Send each API request with two headers:
Authorization: Bearerfollowed by the service token, andDPoPwith a new proof that includesath.
The scheme is Bearer, even though the token’s token_type reads DPoP.
Delete a service account
In the Web App
- On the account’s page, under Delete this service account, click Delete service account.
- 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
- GitHub Actions: OpenID Connect (opens in a new tab): About security hardening with OpenID Connect
- SplitSecure plans (opens in a new tab): See the plans and their limits