Certificate request tokens

Certificate request tokens provide a secure, time-limited mechanism for generating client certificates without requiring direct API access. They act as pre-authorized tokens that contain certificate metadata and can be exchanged for actual client certificates. A certificate request token is a one time token, once used it can't be reused.

Certificate request tokens enable you to generate client certificates through a token-based workflow that simplifies certificate distribution and management. The administrator can pre-configure certificate metadata such as Common Name, Organization, and Organizational Unit, which can be updated later if needed. This approach allows you to delegate certificate creation to systems or users without requiring full API access, making it ideal for scenarios where direct API credentials can't or should not be shared.

How it works

The Certificate Request Token workflow follows these steps:

1. Create Token: An administrator creates a Certificate Request Token with predefined certificate metadata
2. Distribute the enrollment JWT: The administrator retrieves the token's enrollment JWT and shares it with the system or user needing a certificate
3. Redeem the JWT: The recipient sends the enrollment JWT back with a Certificate Signing Request (CSR)
4. Certificate Created: A client certificate is created with the metadata from the token

The enrollment JWT

Each Certificate Request Token has a signed enrollment JWT. This is the single artifact to hand to the end user, and it carries everything the request needs:

• The exact endpoint to send the CSR to, including your Frontdoor identifier, so the recipient assembles no addresses
• The token itself, which authorizes the request
• The certificate subject the request must use
• The expiry, which is the expiry of the underlying token

The JWT replaces the practice of sending a bare token string alongside a URL and an account identifier gathered from elsewhere. Because the endpoint travels inside the signed artifact, there is nothing for the recipient to mistype.

The JWT is a credential. Anyone holding it can obtain the certificate it describes, so share it the way you would share a password. Deleting the Certificate Request Token revokes the JWT immediately, and the JWT stops working as soon as the certificate is issued.

Verifying the enrollment JWT

The enrollment JWT is signed with ES256. The public key is published as a JSON Web Key Set, so a recipient can confirm that a JWT came from Frontdoor before acting on the endpoint inside it:

https://gateway.production.netfoundry.io/frontdoor/v2/public/.well-known/jwks.json

This endpoint needs no authentication and only ever contains public keys. Recipients who automate enrollment should verify the signature against this key set, and check three claims before sending a CSR:

• iss is frontdoor
• aud is the Frontdoor account they expect
• url points at a host they expect

Checking a JWT by hand

To inspect a single JWT, fetch the key set and match the kid in the JWT header against the kid of a published key:

# The kid the JWT was signed with
cut -d. -f1 <<< "$ENROLLMENT_JWT" | base64 -d | jq -r .kid

# The keys currently published
curl -s https://gateway.production.netfoundry.io/frontdoor/v2/public/.well-known/jwks.json

A response looks like this. There is no d member, because that is the private half and it is never published:

{
  "keys": [
    {
      "kty": "EC",
      "kid": "m782cs8g",
      "use": "sig",
      "alg": "ES256",
      "x": "XrT29HujayfQ3cDcwNTEaby3v53EkC01WdWwI0ONHlo",
      "y": "gqxCiFt82H5swoWRvNq9qHrh2Yzf4nUR6Q_PnzM9ywQ",
      "crv": "P-256"
    }
  ]
}

Paste the key with the matching kid into a JWT debugger such as jwt.io to check the signature. A debugger cannot find the key on its own: Frontdoor puts no jku header in the JWT, deliberately, because a verifier that reads its key from a URL inside the token it is verifying has verified nothing. Supply the key yourself.

Or verify from the command line with step:

curl -s https://gateway.production.netfoundry.io/frontdoor/v2/public/.well-known/jwks.json > jwks.json
step crypto jwt verify --jwks jwks.json --iss frontdoor --aud "$FRONTDOOR_ID" < enrollment.jwt

Signing key rotation

The signing key can be replaced. When it is, enrollment JWTs already in circulation keep working:

• The key set holds the new signing key alongside the one it replaced, so a JWT signed earlier still verifies.
• The kid header of each JWT names the key that signed it.
• A superseded key stays published until every JWT it could have signed has expired.

Build your verifier to read the whole key set and select by kid, rather than pinning a single key. A verifier written that way needs no attention when the key changes. Re-read the key set periodically, or whenever you meet a kid you do not recognize.

Token properties

Each Certificate Request Token contains both required and optional certificate metadata that is applied to the generated client certificate.

• Name is the only required field, which becomes the name for the resulting client certificate. This name helps identify and manage certificates within your Frontdoor account.
• Common Name (CN) fixes the subject Common Name for the certificate.
• Organization (O) fixes the Organization for the certificate subject.
• Organizational Unit (OU) fixes the Organizational Unit.

Any of these subject fields that you populate becomes a requirement, not a suggestion. When the end user redeems the enrollment JWT, the subject of their CSR must match the fields the token sets, and a request that disagrees is rejected with an error naming each mismatch. Fields you leave blank place no constraint on the request, so the end user chooses them.

This is what makes a Certificate Request Token safe to hand to someone outside your team: they choose their own private key, and you decide what identity the resulting certificate can claim.

Best practices

Effective token creation starts with using clear, descriptive names that clearly indicate the client certificate's purpose and intended end user. Populate the certificate subject fields whenever you can: they constrain what the resulting certificate can claim, so filling them in is a control rather than a convenience. Always document what each token is intended for, including its purpose, intended recipient, and expected usage timeline for future reference and auditing.

Tell the recipient the subject you have fixed. They need it to build a CSR that the service accepts, and it saves a round trip through a rejected request. The values are in the enrollment JWT, so a recipient who decodes it can read them without asking.

Token lifecycle management

Expiration handling

Token expiration provides an automatic security mechanism that prevents long-term credential exposure:

• Tokens automatically become invalid after their configured expiration time
• Even if compromised, tokens have a limited window of vulnerability
• Expired tokens can't be used to create certificates
• Provides natural cleanup mechanism for certificate infrastructure
• Regularly clean up expired tokens to maintain good security hygiene and prevent system clutter