Page in development
This page is in development and as such, its contents may be incorrect
The security API provides the functionality for obtaining and refreshing the tokens needed for interacting with all Configuration API, Worker Node API and Manager Node API.
Aspire can be configured to restrict the REST APIs so that they only can be accessed through the use of authentication tokens. Any given user or Aspire node must posses a valid authentication 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:
Each REST Endpoint have one of the following security roles associated with them:
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:
{ "$int_perms": [], "sub": "org.pac4j.core.profile.CommonProfile#jdoe", "$int_roles": [ "Administrator" ], "exp": 1601410068, "iat": 1601409768 }
Result fields
Name | Type | Description |
---|---|---|
$int_perms | array | Not used in current security model. |
sub | string | Identifier of user, containing username |
$int_roles | array_string | Array of roles associated with given user |
exp | long | Unix epoch representing when the current JWT token will expire |
iat | long | Unix epoch representing the time of creation of the JWT token |
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 /refresh endpoint for details on how to use them to obtain a new Access Token.
POST /aspire/_api/login
Request Body Parameters
Name | Type | Required | Description |
---|---|---|---|
username | string | Required | Username to authenticate with |
password | string | Required | Password to authenticate with |
Example
POST /aspire/_api/login { "username": "<username-provided-by-user>", "password": "<password-provided-by-user>" }
Response Body Fields
Name | Type | Description |
---|---|---|
accessToken | string | JWT access token |
refreshToken | string | JWT refresh token |
tokenType | string | Token type, always "bearer" |
expiresIn | long | Expiration time in seconds for the access token |
Example:
{ "accessToken": "eyJhb...", "refreshToken": "eyJhb...", "tokenType": "bearer", "expiresIn": 300 }
Status
Response code | Description |
---|---|
200 | Success |
401 | Unauthorized, login failed |
POST /aspire/_api/login/refresh
Request Body Parameters
Name | Type | Required | Description |
---|---|---|---|
refreshToken | string | Required | Refresh token to use for refresh |
Example
POST /aspire/_api/login { "refreshToken": "eyJhb..." }
Response Body Fields
Name | Type | Description |
---|---|---|
accessToken | string | JWT access token |
refreshToken | string | JWT refresh token |
tokenType | string | Token type, always "bearer" |
expiresIn | long | Expiration time in seconds for the access token |
Example:
{ "accessToken": "eyJhb...", "refreshToken": "eyJhb...", "tokenType": "bearer", "expiresIn": 300 }
Status
Response code | Description |
---|---|
200 | Success |
401 | Unauthorized Refresh failed, can be caused by:
|