XIVAuth makes use of JWTs for purposes of attestations, such as proving ownership over a character. The JWT implementation that XIVAuth exposes requires some special considerations in order to keep consumer applications secure. This page documents those considerations, as well as general guidance for ensuring safety while using Attestation JWTs.

<aside> 🔥 This document is still being written, and serves as loose notes right now.

</aside>

• JWTs issued by XIVAuth will always have a kid field in their header to denote which key signed the JWT. Consumers will need to use this kid to find the public key as exposed by JWKS.
• XIVAuth allows consumers to request which algorithm they’d like to have their JWTs signed by. It is the responsibility of the consumer to validate that the algorithm received is the algorithm expected! That is, if you only ever request Ed25519 JWTs, be sure you’re only verifying Ed25519 as an algorithm type!
  • Consumers of the /verify endpoint will have this taken care of for them. XIVAuth will find the kid that generated the key and verify that the algorithm used is allowed for that kid. That is, a kid that refers to an RSA-only key will only verify against the RSA algorithms.
• The JWKS endpoint does not expose the “intended algorithm” for any keys, except for EC keys. Match your keys against the kid instead, and verify your signature types appropriately.
  • An RSA kid will never have HS as a supported algorithm in order to prevent algorithm confusion vulnerabilities.
• If using the HMAC algorithms (HS256 et al), the /verify endpoint is mandatory as key material is not released.

Attestation Format

XIVAuth JWT attestations are normal (mostly-standards-compliant) JWTs, with the following properties in the header:

• The kid field will always be set with the name of the key that signed that JWT.
• The typ field is the type name of the object included in the attestation. This does not follow a standard Media Type, so clients should take care to verify.
  • Character attestations will have a typ of Character.
• The jku field will point to the URL of the JWKS endpoint on XIVAuth. Note that this value is intended to be informational only; any actual checks should be against a hardcoded endpoint.

Likewise, certain properties are defined for bodies of attestation JWTs:

• The jti field will be set to a randomly generated string. This value may be assumed to be unique.
• The iss field will contain the URL pointing to the XIVAuth server that issued the JWT.
  • For production, this will be a hardcoded value of https://xivauth.net/.
• Certain JWT attestations may include an aud field, set to the value https://xivauth.net/applications/{application_id}.
  • If this field is present, the consumer must only accept this JWT if it recognizes the application ID as its own. When performing online verification of the JWT, the audience will be verified against the provided OAuth credentials.
• An iat and exp field will always be present in the JWT body, with a low TTL for expiration. Clients should not implement any skew for these fields.

For security and interop purposes, XIVAuth will also include an optional nonce field in the JWT body. The contents of this field are controlled by the requesting client, and are considered opaque to XIVAuth. API clients are generally advised to set this to a random value to prevent token replay attacks, but clients may choose to send state information if desired.

Supported Algorithms