Versions Compared

Old Version 18

changes.mady.by.user Andres Aguilar

Saved on

compared with

New Version 19

changes.mady.by.user Andres Aguilar

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
The security API provides the functionality for obtaining and refreshing the tokens needed for interacting with all REST APIs:  Configuration API, Worker Node API and Manager Node API.

Table of Contents

Section

Security model

Aspire can be configured to restrict the REST APIs to grant access only through the use of Access Tokens. Any given user or Aspire node must posses a valid Access Token before executing any secured REST API.

Any user or Aspire node will be assigned with a role definition that specifies the level of access to the different REST endpoints, as some endpoints might be restricted to certain roles.

The current existing roles are:

  • Administrator
  • Operator
  • ManagerNode
  • WorkerNode

Each REST Endpoint have one of the following security roles associated with them:

  • Administrator
    • Only Administrator roles can access the endpoint
  • Operator
    • Both Operator and Administrator roles can access the endpoint
  • ManagerNode
    • Ony ManagerNode roles can access the endpoint
  • WorkerNode
    • Only WorkerNode roles can access the endpoint
  • PermitAll
    • Any roles can access the endpoint

Authentication Failure responses

The following are the possible failure status when calling a REST endpoint without logging in, or with insufficient permissions:

Response codeDescription
401

Unauthorized

Either the Access Token was not provided or invalid

403

Forbidden

A valid Access Token was provided, but the user does not have the required roles for calling the given endpoint



Access Tokens

The access tokens are JWT tokens, signed with HS256 algorithm. These tokens are either auto-generated by the Aspire nodes, or requested via the /login endpoint.

An example of the JWT Payload generated for the jdoe user looks like this:

Section
Code Block
languagejs
{
  "sub": "jdoe",
  "roles": [
    "Administrator"
  ],
  "exp": 1601410068,
  "iat": 1601409768
}

JWT Payload fields

NameTypeDescription
substringIdentifier of user, containing username
$int_rolesarray_stringArray of roles associated with given user
explongUnix epoch representing when the current JWT token will expire
iatlongUnix epoch representing the time of creation of the JWT token
Section

Refresh Tokens

Refresh tokens are used to obtain a new valid Access Token when the one previously generated is expired. The refresh tokens also expires, but they usually are configured to live longer than their access token counterpart.

The Aspire refresh tokens are just other JWT tokens generated with longer expiration time. Look at the /login/refresh endpoint for details on how to use them to obtain a new Access Token.



Section

Login Endpoint

Panel
borderColorblack
bgColor#fafafb

POST /aspire/_api/login

Request

Request Body Parameters

NameTypeRequiredDescription
usernamestringRequiredUsername to authenticate with
passwordstringRequiredPassword to authenticate with

Example

Code Block
languagejs
POST /aspire/_api/login
{
  "username": "<username-provided-by-user>",
  "password": "<password-provided-by-user>"
}

Response

Response Body Fields

NameTypeDescription
accessTokenstringJWT access token
refreshTokenstringJWT refresh token
tokenTypestringToken type, always "bearer"
expiresInlongExpiration time in seconds for the access token

Example:

Code Block
languagejs
{
    "accessToken": "eyJhb...",
    "refreshToken": "eyJhb...",
    "tokenType": "bearer",
    "expiresIn": 300
}

In case no authentication is configured, the following response will be returned

Code Block
languagejs
{
    "message": "No authentication is configured"
}

Status

Response codeDescription
200Success
401Unauthorized, login failed



Section

Refresh Endpoint

Panel
borderColorblack
bgColor#fafafb

POST /aspire/_api/login/refresh

Request

Request Body Parameters

NameTypeRequiredDescription
refreshTokenstringRequiredRefresh token to use for refresh

Example

Code Block
languagejs
POST /aspire/_api/login/refresh
{
  "refreshToken": "eyJhb..."
}

Response

Response Body Fields

NameTypeDescription
accessTokenstringJWT access token
refreshTokenstringJWT refresh token
tokenTypestringToken type, always "bearer"
expiresInlongExpiration time in seconds for the access token

Example:

Code Block
languagejs
{
    "accessToken": "eyJhb...",
    "refreshToken": "eyJhb...",
    "tokenType": "bearer",
    "expiresIn": 300
}

Status

Response codeDescription
200Success
401

Unauthorized

Refresh failed, can be caused by:

  • Invalid refresh token
  • Expired refresh token
  • Already used refresh token