Authorization
Authorize with the Provide stack
Bearer Authorization
Provide requires the presence of a bearer
API token to authorize most API calls. A bearer
API token is an encoded JWT which contains a subject claim (sub
) which references an authorized entity (i.e., the User
, Application
or Organization
). The authorized entity uses a signed bearer
authorization Token
to access one or more resources for which the Token
was authorized. Unless otherwise noted, all API requests must include a header such as Authorization: bearer <jwt>
.
Authentication/Authorization JWT's for users, organizations and applications/workgroups can be obtained through the Provide-CLI or through Ident API.
Access/Refresh Tokens
In accordance with the OAuth 2.0 specification, when an entity is authorized and the requested scope
includes offline_access
, a refresh token is vended and returned on behalf of the caller. This refresh token is long-lived and can be used to authorize short-lived access tokens using the refresh_token
grant type on subsequent authorization requests.
This pattern is useful for machine-to-machine applications; a secure practice is to store the long-lived refresh token in a Vault instance (i.e., as a secret), read it into application memory during container initialization and then use it to authorize a short-lived access token. If the container remains running long enough for the access token to expire, the refresh token should once again be used to seamlessly authorize a new access token.
Encoded JWT
The standard and application-specific bearer
claims are encoded as JWT and signed using the RS256
(RSA Signature with SHA-256) or Ed25519
(Edwards-curve Digital Signature) algorithm.
Header
When verifying a JWT, the algorithm used for signing and an identifier referencing the public key to use for signature verification can be found in the alg
and kid
headers, respectively:
Additional details related to signature verification can be found here.
Payload
The encoded JWT will, in most cases, include an expiration timestamp (exp
) after which the token is no longer valid. A Token
issued without an expiration date (i.e., certain machine-to-machine API tokens) must be explicitly revoked.
The following payload illustrates how standard and application-specific claims are encoded in a bearer
JWT:
Claims
The following claims are typically included in the signed token payload:
Signature Verification
The encoded JWT is signed using the the RS256
(RSA Signature with SHA-256) or Ed25519
(Edwards-curve Digital Signature) algorithm. The following public key can be used to verify the signature:
Last updated