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:

ClaimFieldDescription

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

Authenticate User

Authenticates a User; to create a User, see Create User via the Ident API or the Provide-CLI.

Authenticate User

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

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

Request Body

NameTypeDescription

email

string

email of

User

requiring authentication

password

string

password of

User

requiring authentication

{
    "user": {
        "id": "49a02f33-33f2-4d69-a301-ffb1933e77cc",
        "created_at": "2021-08-11T03:38:36.24522Z",
        "name": "John Young",
        "first_name": "John",
        "last_name": "Young",
        "email": "johnyoung@provide.local",
        "permissions": 415,
        "privacy_policy_agreed_at": "2021-08-11T03:38:36.24522Z",
        "terms_of_service_agreed_at": "2021-08-11T03:38:36.24522Z"
    },
    "token": {
        "id": "7b97155e-58e7-4d17-8771-22c650ffc2c2",
        "expires_in": 86400,
        "token": "<JWT>",
        "permissions": 415
    }
}

Authorize Token

Authorize a Token for a User, Organization or Application

Authorize Token

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

Authorize aTokenon behalf of a User, Organization or Application

Headers

NameTypeDescription

authorization*

string

bearer scoped to anApplication, Organization or User granting the token

Request Body

NameTypeDescription

application_id

string

id of the target Application

organization_id

string

id of the target Organization

user_id

string

id of the target User

scope

string

authorization scope; for long-lived token use offline-access

{
    "id": "dc501654-6d42-4f85-8704-fc7e638b7065",
    "token": "<JWT>",
    "permissions": 510
}

List Revocable Tokens

Returns a list of tokens that are capable of being revoked

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

NameTypeDescription

authorization

string

bearer scoped to a

Application

,

Organization

or

User

[
    {
        "id": "38952726-a0e8-4e63-8e3f-0ca598b3b57f",
        "created_at": "2020-12-16T05:44:12.586171Z",
        "token": "<JWT>"
    },
    {
        "id": "0308ba6b-d541-4f6d-a09f-a4711ae77a2d",
        "created_at": "2020-12-19T06:01:01.096896Z",
        "token": "<JWT>"
    },
    {
        "id": "eed98488-0334-4624-8000-9c55c44de9c6",
        "created_at": "2020-12-19T06:57:37.597694Z",
        "token": "<JWT>"
    }
]

Revoke Token

Revokes a specified Token

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

NameTypeDescription

id

string

id of

Token

to be revoked

Headers

NameTypeDescription

authorization

string

<JWT> scoped to the

Application

,

Organization

or

User

PreviousUsersNextPermissions

Last updated