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.
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
The roles are assigned based on the Authentication and Authorization Settings. See Security Settings for information on how to configure this.
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 code | Description |
|---|---|
| 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:
{
"sub": "jdoe",
"roles": [
"Administrator"
],
"exp": 1601410068,
"iat": 1601409768
}
JWT Payload fields
| Name | Type | Description |
|---|---|---|
| sub | string | Identifier of user, containing username |
| 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
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.
Login Endpoint
POST /aspire/_api/login
Request
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
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
}
In case no authentication is configured, the following response will be returned
{
"message": "No authentication is configured"
}
Status
| Response code | Description |
|---|---|
| 200 | Success |
| 401 | Unauthorized, login failed |
A Cookie will also be returned to persist both the access and refresh tokens
Basic Login Endpoint
GET /aspire/_api/login/basic
Request
HTTP Headers parameters
| Name | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Required | Base64 encoded user:password |
Example
To login with "user:pass" the Base64 would be dXNlcjpwYXNz
GET /aspire/_api/login/basic - Authorization: Basic dXNlcjpwYXNz
Response
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
}
In case no authentication is configured, the following response will be returned
{
"message": "No authentication is configured"
}
Status
| Response code | Description |
|---|---|
| 200 | Success |
| 401 | Unauthorized, login failed |
A Cookie will also be returned to persist both the access and refresh tokens
Refresh Endpoint
POST /aspire/_api/login/refresh
Request
Request Body Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| refreshToken | string | Required | Refresh token to use for refresh |
Example
POST /aspire/_api/login/refresh
{
"refreshToken": "eyJhb..."
}
Response
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:
|
Revoke Endpoint
POST /aspire/_api/login/revoke
Request
Request Body Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| refreshToken | string | Required | Refresh token to use for revoke |
Example
POST /aspire/_api/login/revoke
{
"refreshToken": "eyJhb..."
}
Response
Blank response
Status
| Response code | Description |
|---|---|
| 200 | Success |
| 400 | Bad request Refresh failed, can be caused by:
|
Overview
Content Tools
Copyright © 2024 Accenture
