diff --git a/IdentityServer/v7/docs/content/tokens/reference.md b/IdentityServer/v7/docs/content/tokens/reference.md index df9fa5f8..3216da7e 100644 --- a/IdentityServer/v7/docs/content/tokens/reference.md +++ b/IdentityServer/v7/docs/content/tokens/reference.md @@ -25,4 +25,7 @@ The introspection endpoint requires authentication - since the client of an intr ApiSecrets = { new Secret("secret".Sha256()) } Scopes = { "read", "write" } } -``` \ No newline at end of file +``` + +## Store Keys and Handles +Reference tokens have a key, which is an internal identifier used in the data store, and a handle, which is an external value that is given to the client and never stored. The handle is 32 bytes of cryptographically strong random data encoded as a hex string with a suffix to indicate the encoding ("-1"). This is the value that clients use as the access token. The handle, plus additional metadata indicating the type of grant, is hashed with the SHA-256 algorithm to produce the key. When IdentityServer is presented with a handle, it recomputes the key in order to retrieve the persisted grant record for the reference token. The intention of this separation of key and handle is that read access to the store will not reveal sensitive data. An attacker could read the keys in the data store, but those keys were produced using a one-way hash, so the attacker would not be able to use the keys to recover the handles (the actual access tokens).