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 HS256 as a keypair.
• If using the HMAC algorithms (HS256 et al), the /verify endpoint is mandatory.

Attestation Format

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

• The kid field in the JWT header will always be set with the name of the key that signed that JWT.
• An iat and exp field will always be present in the JWT body, with a low TTL for expirations. Clients should not implement any skew for these fields.

Supported Algorithms

XIVAuth currently supports the following algorithms:

• HMAC: HS256, HS384, HS512
  • Requires online verification to use!
• RSASSA-PKCS1-v1_5: RS256, RS384, RS512
• RSASSA-PSS: PS256, PS384, PS512
• ECDSA: ES256, ES384, ES512
• EdDSA: EdDSA, ED25519 (not in spec)

Consumers are recommended to use the EdDSA algorithm when possible, with RS256 or PS256 serving as a fallback. In most cases, if an algorithm is not specified, XIVAuth will provide an EdDSA JWT.