Authentication

The Fabric Services System REST API supports authentication through a bearer API token. The user provides the username and password in an initial request and the REST API returns a token that is valid for a limited period and can be used to make subsequent requests.

By using Keycloak as the authentication and authorization backend of the API, the Fabric Services System REST API follows the OAuth2 (OpenID) authentication flow, which provides the client with the required OAuth2 tokens needed to authenticate subsequent API calls.

Getting the API token

To obtain an API authentication token, send a POST /rest/auth/login request with the required request POST data. This request returns the authentication information, including the access token. You can then use this access token for the actual API requests.

The POST data has the following format:

{
    "username": "<username>",
    "password": "<password>"
}

The authentication POST request response has the following format:

{
    "access_token": "<access token>",
    "id_token": "<id token>",
    "session_state: "",
    "scope": "",
    "refresh_token": "<refresh token>",
    "token_type": "Bearer",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "not-before-policy": 0
}

The following table describes the fields in the authentication POST request.

Table 1. Field definitions
Field	Format	Description
`access_token`	String	This field specifies the access token to use for API calls toward the REST API.
`expires_in`	Integer	This field specifies how long the access token is valid, in seconds. Default: 300
`id_token`	JWT	This field specifies a JSON web token, which is not necessary for the actual API requests; it contains information from the Keycloak environment.
`not-before-policy`	Integer	This field specifies a custom value that indicates a time during which all tokens are invalid (unused by the Fabric Services System REST API).
`refresh_expires_in`	Integer	This field specifies how long the refresh token is valid, in seconds. Default: 1800
`refresh_token`	String	This field specifies contains the refresh token that you can use to refresh the existing authentication (access token) after it expires and before the refresh token expires.
`scope`	Space-separated strings	This field specifies the OAuth2/OIDC scope of the token. For new authentications, this field is expected to be empty.
`session_state`	String	This field specifies is an optional internal session identifier. For new authentications, this field is expected to be empty.
`token_type`	String	This field specifies is always set to Bearer.

Successful authentication request and response

Authentication request:

$ curl -s -v -XPOST -d '{"username":"admin","password":"NokiaFss1!"}' -H "Content-Type: application/json; charset=utf-8" "https://fss.domain.tld/rest/auth/login"

Authentication response:

...
> POST /rest/auth/login HTTP/2
> Host: fss.domain.tld
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Type: application/json; charset=utf-8
> Content-Length: 44
>
...
< HTTP/2 200
< content-type: application/json; charset=utf-8
< date: Tue, 19 Jul 2022 23:20:34 GMT
< x-content-type-options: nosniff
< x-frame-options: SAMEORIGIN
< x-xss-protection: 1; mode=block
<
{
  "access_token": "eyJhbGciOiJSUzI...PQZUPN4BVu7tCT6qy7Q",
  "id_token": "eyJhbGciOiJSUzI...JMXlQi8y0KknyCVg9FQ",
  "session_state": "",
  "scope": "",
  "refresh_token": "eyJhbGciOiJIUzI1...V4_P0sNqZRjOBQ7ego",
  "token_type": "Bearer",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "not-before-policy": 0
}

Unsuccessful authentication response request

Authentication request:

$ curl -s -v -XPOST -d '{"username":"admin","password":"wrongpassword"}' -H "Content-Type: application/json; charset=utf-8" "https://fss.domain.tld/rest/auth/login"

Authentication response:

...
> POST /rest/auth/login HTTP/2
> Host: fss.domain.tld
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Type: application/json; charset=utf-8
> Content-Length: 47
>
...
< HTTP/2 400
< content-type: application/json; charset=utf-8
< date: Tue, 19 Jul 2022 23:25:10 GMT
< x-content-type-options: nosniff
< x-frame-options: SAMEORIGIN
< x-xss-protection: 1; mode=block
<
{
  "type": "/auth/errors?key=token-error",
  "title": "TOKEN_ERROR",
  "detail": "Failed to get access token. failed to get token error : invalid_grant",
  "object_ref": "/auth/login",
  "status": 400
}

Refreshing the authentication API token

By default, the authentication token expires every 300 seconds. Refreshing the authentication API token does not require the use of the username or password; instead, use the refresh_token field. When you use the access_token and refresh_token fields, a new access_token and a new refresh_token is generated, which can be used again for 5 minutes. You refresh the authentication token by creating a POST /rest/auth/refresh request with the required POST data and the correct Authorization: Bearer <expired access token> header. This request returns the authentication information, including the access token that is used for the actual API requests.

The authentication refresh POST request data has the following format:

{
  "refresh_token":"eyJhbGciOiJIUzI1...V4_P0sNqZRjOBQ7ego"
}

Successful REST API authentication refresh request and response

Authentication refresh request:

$ curl -s -v -XPOST -d '{"refresh_token":"eyJhbGciOiJIUzI1...V4_P0sNqZRjOBQ7ego"}' -H "Authorization: Bearer eyJhbGciOiJSUzI...PQZUPN4BVu7tCT6qy7Q" -H "Content-Type: application/json; charset=utf-8" "https://fss.domain.tld/rest/auth/refresh"
> POST /rest/auth/refresh HTTP/2

Authentication refresh response:

> Host: fss.domain.tld
> User-Agent: curl/7.64.1
> Accept: */*
> Authorization: Bearer eyJhbGciOiJSUzI...PQZUPN4BVu7tCT6qy7Q
> Content-Type: application/json; charset=utf-8
> Content-Length: 3325
>
...
< HTTP/2 200
< content-type: application/json; charset=utf-8
< date: Tue, 19 Jul 2022 23:37:22 GMT
< x-content-type-options: nosniff
< x-frame-options: SAMEORIGIN
< x-xss-protection: 1; mode=block
<
{                 
  "access_token": "eyJhbGciOiJSUzI...Z0NmcOQthgEM2PfgA_g",
  "id_token": "eyJhbGciOiJSUzI...ZkNi8yReIyQM0FVt0rw",
  "session_state": "f7d9f6bc-7ab7-448a-8529-53d110e7ed8d",
  "scope": "openid",
  "refresh_token": "eyJhbGciOiJIUzI...eFXnTrYDEZmi8sH9Iwo",
  "token_type": "Bearer",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "not-before-policy": 0
}

Unsuccessful REST API Authentication refresh request and response

Authentication refresh request:

$ curl -s -v -XPOST -d '{"refresh_token":"eyJhbGciOiJIUzI1...V4_P0sNqZRjOBQ7_WRONG"}' -H "Authorization: Bearer eyJhbGciOiJSUzI...PQZUPN4BVu7tCT6qy7Q" -H "Content-Type: application/json; charset=utf-8" "https://fss.domain.tld/rest/auth/refresh"

Authentication refresh response:

> POST /rest/auth/refresh HTTP/2
> Host: fss.domain.tld
> User-Agent: curl/7.64.1
> Accept: */*
> Authorization: Bearer eyJhbGciOiJSUzI...PQZUPN4BVu7tCT6qy7Q
> Content-Type: application/json; charset=utf-8
> Content-Length: 3325
>
...
< HTTP/2 400
< content-type: application/json; charset=utf-8
< date: Tue, 19 Jul 2022 23:50:58 GMT
< x-content-type-options: nosniff
< x-frame-options: SAMEORIGIN
< x-xss-protection: 1; mode=block
<
{
  "type": "/auth/errors?key=token-error",
  "title": "TOKEN_ERROR",
  "detail": "Failed to get access token. failed to get token error : invalid_grant",
  "object_ref": "/auth/refresh",
  "status": 400
}

Using the Swagger UI to authenticate

You can use the Auth Manager service from the Swagger UI to authenticate using the Auth service.

From Auth Manager, under the Auth, click the /auth/login API request, then click Try it out.
The password and username fields become editable in the request body.
Fill in the correct username and password in the fields, then click Execute.

The Responses section displays the access token. This token is valid for 5 minutes.
Copy the access token value.
Click the Authorize button and, in the Available authorizations form that displays, paste the token in the Value field.