Authorization

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:

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

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

Authorize Token

POST https://ident.provide.services/api/v1/tokens

Authorize a Token on behalf of a User, Application or Organization Returns an authorized JSON formatted JWT with an offline-access scoped long-term access_token that serves as authentication for related requests. The scope defined in the <JWT> passed for authorization will serve as the host entity. For example, if you would like to authenticate a user to work within an Application, the <JWT> would be scoped for the target application and the user_id would be passed in the body of the request. This API can be used to authorize OAuth2.

Headers

Name	Type	Description
authorization	string	bearer <JWT> scoped to an Application, Organization or User granting the token

Request Body

Name	Type	Description
application_id	string	id of the target Application
organization_id	string	id of the target Organization
user_id	string	id of the target User

201: Created

{
    // Response
}

Authenticate User

POST https://ident.provide.services/api/v1/authenticate

Authenticates a user with the given parameters.; returns a <JWT> scoped to the user provided

Request Body

Name	Type	Description
email	string	email of User requiring authentication
password	string	password of User requiring authentication

201: Created

{
    // Response
}

List Revocable Tokens

GET https://ident.provide.services/api/v1/tokens

Returns a list of tokens that can be revoked; revocable tokens only include those that are scoped for long-term access.

Headers

Name	Type	Description
authorization	string	bearer <JWT> scoped to a Application, Organization or User

200: OK

{
    // Response
}

Revoke Token

DELETE https://ident.provide.services/api/v1/tokens/:id

Revokes a previously authorized Token Token revocation may be necessary if the Token has become compromised or otherwise requires invalidation. Revocation of a Token should only be necessary on Application or otherwise permanent issuances.

Path Parameters

Name	Type	Description
id	string	id of Token to be revoked

Headers

Name	Type	Description
authorization	string	<JWT> scoped to the Application, Organization or User

204: No Content

{
    // Response
}