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

You obtain an API authentication token by making 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
}
Table 1. Field definitions
Field Format Description
access_token String The access token to use for API calls toward the REST API.
expires_in Integer This fields specifies wow long the access token is valid, in seconds. Default: 300
id_token JWT A JSON web token, which is not necessary for the actual API requests. It contains information from the Keycloak environment.
not-before-policy Integer 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 How long the refresh token is valid, in seconds. Default: 1800
refresh_token String Contains the refresh token that can be used to refresh the existing authentication (access token) after it expires and before the refresh token expires.
scope Space separated strings The OAuth2/OIDC scope of the token. For new authentications, this field expected to be empty.
session_state String An optional internal session identifier. For new authentications, this field is expected to be empty.
token_type String 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, you use the refresh_token field. When you use the access_token and refresh_token fields, a new access_token and 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.

  1. 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.
  2. 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.
  3. Copy the access token value.
  4. Click the Authorize button and in the Available authorizations form that displays, paste the token in the Value field.