Token payload documentation lacks details

[kornelski]

Existing documentation URL(s)

https://developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/application-token/#payload

What changes are you suggesting?

Documentation for JWT fields is shallow, saying very little besides only the name of the field. Since validation of these fields may be critical for security, I would like to have more in-depth information to be sure I'm not making wrong assumptions.

The docs send me to jwt.io for more info, but I'm not keen on that: a) going to another site and searching the whole RFC makes this harder than getting all relevant information from the docs, b) the RFC won't have anything about how Cloudlfare in particular uses these fields — how they are configured, and how they relate to CF's account management.

Field Description
aud The audience tag for the application to which the token is issued.

What's the correct aud value for my account/application? Where do I set that? How do I validate it? Can I hardcode the value, or will it change? Is this value public or private?

If I go to Access > Applications and click on my application's name, I get a slide-in right sidebar with basic information, but the audience tag is not listed there.

email The email address of the user.

Is the email address verified, or can it be spoofed? Is it always available?

iss The Cloudflare Access domain URL for the application.

Do I need to validate this field, or is checking aud enough?

identity_nonce A nonce used to get the user’s identity.

The linked page doesn't say anything about the nonce. Is it only for querying the identity, or do I need to check uniqueness of the nonces myself? Or is it perhaps a cache key for the identity details?

sub The ID of the user.

What's the scope of this ID? Is it per app, or global (can I correlate users across applications with this)? How stable is it? I've noticed it's an empty string when using Service Auth token — that's a pretty big caveat not mentioned in the docs!

There's no mention of common_name.

It's not specified which fields are optional.

[kornelski]

It's also not documented how these fields differ when using Service Auth.