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>
.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.
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.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:{
"alg": "RS256",
"kid": "e6:f7:d5:24:e2:59:06:2b:bc:a2:8c:35:9d:ca:0a:87",
"typ": "JWT"
}
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:{
"aud": "https://ident.provide.services/api/v1",
"exp": 1599896478,
"iat": 1599810078,
"iss": "https://ident.provide.services",
"jti": "54b84bdb-db5b-4c91-a9a1-e3d4abaf9dac",
"nats": {
"permissions": {
"subscribe": {
"allow": [
"baseline.inbound",
"user.2f18c7a7-5540-476c-a7a8-d5b30d2c90e6",
"network.*.connector.*",
"network.*.status",
"platform.>"
]
}
}
},
"prvd": {
"permissions": 536878465,
"user_id": "2f18c7a7-5540-476c-a7a8-d5b30d2c90e6"
},
"sub": "user:2f18c7a7-5540-476c-a7a8-d5b30d2c90e6"
}
The following claims are typically included in the signed token payload:
Claim | Field | Description |
Audience | aud | the intended principal recipients who will process the token |
Expiration | exp | the expiration time, expressed as a unix timestamp |
Issued At | iat | the time the token was issued, expressed as a unix timestamp |
Issuer | iss | the principal who issued and signed the token |
Identifier | jti | unique identifier (UUID) for the token |
NATS | nats | NATS application-specific claims, such as permissions |
Not Before | nbf | optional time the token becomes valid, expressed as a unix timestamp |
Provide | prvd | Provide application-specific claims, in the context of sub |
Subject | sub | principal for which the token was vended |
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:-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0yqdJMBej1X8WwMMkMZw
DV6zZzup4RHLcln0xfGSm6dMPBDM1G96fuHhOwH5+uU5MQHJP7RqW71Bu5dLIG8Z
RX+XyUtb0sxCV/7X27Nm/bKpDysaSWQ36reAmw5wVaB1SoFeN519FY5rhoCWmH3W
auBAHTzpjg57p7uR0XynYXf8NSGXlysWHppkppqwrPH64G6UZaB7SMl1PFfkJeqZ
zJpzBGYWsixdF1EjXn+Yz0mhUZO2OSPWifOuN7cpn3BuNqegg4iVdz5HDoQhJW7N
uRhf3buKd/mjat8XA3e2Rkrr2h835GloScJkj7I4BZUNkzKQuEK6C9xW/zJtbPqQ
RYEq84A1hMfSZ3G5HFe2JkqiyvXkFwS3qMc5Pur8tZSzBj6AYMoJJso/aOdphpR8
6MaaWXWTwvwfpZbMRqehOcsmQcNLF2gLJPuHzR5WtVCnWrDgvjsWyeDD1WISKusi
aOeHxZjS3Bjl4Imq48l1wi2eI/11F/Xg70F4FJaMYLVHJA2nsmBuuQ9UDYHHq876
clKvIvgIItzJcv9lnmjl1Jks1DwCUF3qF2ugYcs9A3EoEcNzhMgZNJ2j5OUzfx1E
bzVKkqoC9MQpZWXgqV0KQqKK4I3rMY+1hLqk4S4eF9ZAVlT33qfMzlf0qWTOcP1Z
i2dsm0fy4NxWxknlEn5/LhMCAwEAAQ==
-----END PUBLIC KEY-----
post
https://ident.provide.services
/api/v1/tokens
Authorize Token
post
https://ident.provide.services
/api/v1/authenticate
Authenticate User
get
https://ident.provide.services
/api/v1/tokens
List Revocable Tokens
delete
https://ident.provide.services
/api/v1/tokens/:id
Revoke Token
Last modified 1yr ago