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:
| Claim | Field | Description |
|---|---|---|
Audience |
| the intended principal recipients who will process the token |
Expiration |
| the expiration time, expressed as a unix timestamp |
Issued At |
| the time the token was issued, expressed as a unix timestamp |
Issuer |
| the principal who issued and signed the token |
Identifier |
| unique identifier (UUID) for the token |
NATS |
| NATS application-specific claims, such as |
Not Before |
| optional time the token becomes valid, expressed as a unix timestamp |
Provide |
| Provide application-specific claims, in the context of |
Subject |
| principal for which the token was vended |
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