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>.

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:

{
  "alg": "RS256",
  "kid": "e6:f7:d5:24:e2:59:06:2b:bc:a2:8c:35:9d:ca:0a:87",
  "typ": "JWT"
}

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:

{
  "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"
}

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:

-----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-----