Fabric secures and controls Web Services (WS) access via an authentication and authorization mechanism in which each API call must be verified.
Fabric supports several methods for that purpose:
API Key - a token which is sent as Authorization: Bearer
header
JWT (JSON Web Tokens) - an open industry standard method (RFC 7519) that represents claims between two parties in a secured manner.
The JWT authentication has 2 variant types:
a. Signed by Fabric
b. Signed by the WS client
Although the preferred way to send the JWT authentication is as an Authorization: Bearer
header, it can also be sent as a cookie.
Open Auth (OAuth) - an authorization delegation protocol. An OAuth Access Token is a string used by a client to make requests to Fabric. This token (self-encoded JWT) is sent as Authorization: Bearer
header.
Basic Authentication - an authentication method built into an HTTP protocol. A client provides a username and a password to make requests to Fabric. These credentials are sent as Authorization: Basic
header.
API key authentication is the simplest method because it can authenticate WS calls simply by including a single key, which also allows a client to make calls easily from various origins.
The API Key is sent as the token value of the Authorization: Bearer
header, for example: Authorization: Bearer ABC
, where the API Key is "ABC".
See here how to generate an API Key.
The authorization and permissions are assigned according to the roles associated with the API Key and its corresponding permissions. See here for more information about API Keys, roles, and permissions.
The authentication flow for this method works as follows:
Create an API Key. See here for instructions. To indicate that JWT is signed by Fabric, do not select the "secured" option.
Make a first POST call to the Fabric server's endpoint: <SERVER-HOST>:<SERVER-PORT>/api/authenticate
, where it provides one of the following credentials in the post body:
{"username": "<USER>", "password": "<PASSWORD>"}
.{"apikey": "<APIKEY>"}
. See here how to generate an API Key (choose the "non secured" key).Upon authentication success, Fabric responds with {"response": "OK"}
(within 201 response code), along with the JWT, which is returned as a cookie.
Make the following web services calls by sending this JWT as the token value of the Authorization: Bearer
header or as a cookie, as part of each request. If requests are made via the browser, this cookie is already stored in the browser.
When used in the cookie, the JWT expiration is automatically extended on each call, whereas it is not extended when using the Bearer header to pass the JWT.
The authorization and permissions are performed according to the credentials provided during the initial "/api/authenticate" call, either by the user or the API Key, along with the assigned roles for each. See here for more information about API Keys, roles, and permissions.
The authentication flow for this method works as follows:
Authorization: Bearer
header.The authorization and permissions are assigned according to the roles associated with the API Key and its corresponding permissions. See here for more information about API Keys, roles, and permissions.
In some cases, the client itself, a service within the organization that calls Fabric, has already authenticated the user (human or another system). For example, the client can be a service that interacts with an IDP (Identity Provider) to authenticate users by using SAML. In such a case, the client holds the actual user and the groups to which they are assigned, and upon which Fabric is to act. For example, Fabric uses this information for role permissions.
Fabric supports these delegated authentications:
This option requires an extra security verification:
The user and group lists shall be sent as part of the JWT payload claims - unm
for the user and bgr
for the group list, using an array structure. Here is a JWT example:
{
"apk": "apikeyWithSAML",
"unm": "jhon.doe@k2view.com",
"bgr": [
"tester1",
"testGroupLeaders"
]
}
Fabric supports the standard Open Auth (OAuth) protocol for its web services authorization. Using the OAuth requires the following preparations:
[oauth2]
## The JSON Web Key (JWK)'s endpoint that holds the keys for the access token (JWT) verification
JWK_ENDPOINT=https://<auth-server>/jwks
By default, it is expected that the scope's claim name is "scope". If another is sent, add this parameter ACCESS_TOKEN_SCOPE_PROPERTY_NAME to the config.ini and set its value (for example: ACCESS_TOKEN_SCOPE_PROPERTY_NAME="scp" ).
Fabric extends the standard OAuth authorization capabilities beyond the provided scopes: The access token (JWT) can be sent with an extra optional payload parameter, representing the client ID. This ID should be mapped to APIKEY in Fabric, and it should be granted the necessary permissions. By default, the name of this optional parameter is "client_id".
Fabric adheres to the OAuth standards for verifying web service API calls. When a client requests a web service:
Authorization: Bearer
header.Note: Fabric, as the Resource Server, supports both OAuth grant types, i.e., Authorization Code and Client Credentials.
Basic authentication, also known as Basic Access Authentication, is a method for an HTTP user-agent to authenticate itself by providing a username and password when making a request. The client sends HTTP requests with the Authorization
header that contains the word Basic
followed by a space and a base64-encoded string of username:password
.
Note: Basic authentication should only be used together with the HTTPS/SSL mechanism. For more information, refer to Fabric Hardening.
The authorization and permissions are assigned according to the roles assigned to the user and their associated permissions. See here for more information about API Keys, roles, and permissions.
The Fabric Basic Authentication mechanism provides a helper when calls are originated from a web browser that does not support sending request headers.
To activate the helper, add this additional parameter to the web service request: basicAuth=true
.
When activated, a browser pop-up will appear when the request is sent. The user can populate the pop-up fields with the username and password.
There are two options to generate an API key: either via the Web Framework Admin or by using a Fabric command. In both cases, you can choose whether the API Key shall be secured or not, as described below.
Web Framework Admin:
Open the Admin Panel web page and select Admin > Security and then click the API keys tab.
Click the Add API Key + button on the upper right of the window.
Fill in the Name (Mandatory) and choose if it shall be secured (Optional) by using the checkbox on the page.
Click Save.
When the secured option has been selected, the secret key is displayed in a pop-up window and can be copied for later use. The secret key is used to sign the JWT.
For example:
Fabric command: CREATE TOKEN <'token_name'> [SECURED]
. When "SECURED" is used, the secret key is retrieved.
For example:
create token 'Secured1' SECURED;
|Secretkey |
+------------------------------------+
|c55a86d1-9de6-4aaa-bf9e-cedf1391c95b|
If the secured option has not been selected, the token name is used as the token value for the API Key Authentication method.
Web services authentication is done either by user or by API key, where each can be assigned to roles and accordingly to permissions.
Read this article for the list of supported roles, and then click here to learn how to grant permissions to specific roles.
Fabric secures and controls Web Services (WS) access via an authentication and authorization mechanism in which each API call must be verified.
Fabric supports several methods for that purpose:
API Key - a token which is sent as Authorization: Bearer
header
JWT (JSON Web Tokens) - an open industry standard method (RFC 7519) that represents claims between two parties in a secured manner.
The JWT authentication has 2 variant types:
a. Signed by Fabric
b. Signed by the WS client
Although the preferred way to send the JWT authentication is as an Authorization: Bearer
header, it can also be sent as a cookie.
Open Auth (OAuth) - an authorization delegation protocol. An OAuth Access Token is a string used by a client to make requests to Fabric. This token (self-encoded JWT) is sent as Authorization: Bearer
header.
Basic Authentication - an authentication method built into an HTTP protocol. A client provides a username and a password to make requests to Fabric. These credentials are sent as Authorization: Basic
header.
API key authentication is the simplest method because it can authenticate WS calls simply by including a single key, which also allows a client to make calls easily from various origins.
The API Key is sent as the token value of the Authorization: Bearer
header, for example: Authorization: Bearer ABC
, where the API Key is "ABC".
See here how to generate an API Key.
The authorization and permissions are assigned according to the roles associated with the API Key and its corresponding permissions. See here for more information about API Keys, roles, and permissions.
The authentication flow for this method works as follows:
Create an API Key. See here for instructions. To indicate that JWT is signed by Fabric, do not select the "secured" option.
Make a first POST call to the Fabric server's endpoint: <SERVER-HOST>:<SERVER-PORT>/api/authenticate
, where it provides one of the following credentials in the post body:
{"username": "<USER>", "password": "<PASSWORD>"}
.{"apikey": "<APIKEY>"}
. See here how to generate an API Key (choose the "non secured" key).Upon authentication success, Fabric responds with {"response": "OK"}
(within 201 response code), along with the JWT, which is returned as a cookie.
Make the following web services calls by sending this JWT as the token value of the Authorization: Bearer
header or as a cookie, as part of each request. If requests are made via the browser, this cookie is already stored in the browser.
When used in the cookie, the JWT expiration is automatically extended on each call, whereas it is not extended when using the Bearer header to pass the JWT.
The authorization and permissions are performed according to the credentials provided during the initial "/api/authenticate" call, either by the user or the API Key, along with the assigned roles for each. See here for more information about API Keys, roles, and permissions.
The authentication flow for this method works as follows:
Authorization: Bearer
header.The authorization and permissions are assigned according to the roles associated with the API Key and its corresponding permissions. See here for more information about API Keys, roles, and permissions.
In some cases, the client itself, a service within the organization that calls Fabric, has already authenticated the user (human or another system). For example, the client can be a service that interacts with an IDP (Identity Provider) to authenticate users by using SAML. In such a case, the client holds the actual user and the groups to which they are assigned, and upon which Fabric is to act. For example, Fabric uses this information for role permissions.
Fabric supports these delegated authentications:
This option requires an extra security verification:
The user and group lists shall be sent as part of the JWT payload claims - unm
for the user and bgr
for the group list, using an array structure. Here is a JWT example:
{
"apk": "apikeyWithSAML",
"unm": "jhon.doe@k2view.com",
"bgr": [
"tester1",
"testGroupLeaders"
]
}
Fabric supports the standard Open Auth (OAuth) protocol for its web services authorization. Using the OAuth requires the following preparations:
[oauth2]
## The JSON Web Key (JWK)'s endpoint that holds the keys for the access token (JWT) verification
JWK_ENDPOINT=https://<auth-server>/jwks
By default, it is expected that the scope's claim name is "scope". If another is sent, add this parameter ACCESS_TOKEN_SCOPE_PROPERTY_NAME to the config.ini and set its value (for example: ACCESS_TOKEN_SCOPE_PROPERTY_NAME="scp" ).
Fabric extends the standard OAuth authorization capabilities beyond the provided scopes: The access token (JWT) can be sent with an extra optional payload parameter, representing the client ID. This ID should be mapped to APIKEY in Fabric, and it should be granted the necessary permissions. By default, the name of this optional parameter is "client_id".
Fabric adheres to the OAuth standards for verifying web service API calls. When a client requests a web service:
Authorization: Bearer
header.Note: Fabric, as the Resource Server, supports both OAuth grant types, i.e., Authorization Code and Client Credentials.
Basic authentication, also known as Basic Access Authentication, is a method for an HTTP user-agent to authenticate itself by providing a username and password when making a request. The client sends HTTP requests with the Authorization
header that contains the word Basic
followed by a space and a base64-encoded string of username:password
.
Note: Basic authentication should only be used together with the HTTPS/SSL mechanism. For more information, refer to Fabric Hardening.
The authorization and permissions are assigned according to the roles assigned to the user and their associated permissions. See here for more information about API Keys, roles, and permissions.
The Fabric Basic Authentication mechanism provides a helper when calls are originated from a web browser that does not support sending request headers.
To activate the helper, add this additional parameter to the web service request: basicAuth=true
.
When activated, a browser pop-up will appear when the request is sent. The user can populate the pop-up fields with the username and password.
There are two options to generate an API key: either via the Web Framework Admin or by using a Fabric command. In both cases, you can choose whether the API Key shall be secured or not, as described below.
Web Framework Admin:
Open the Admin Panel web page and select Admin > Security and then click the API keys tab.
Click the Add API Key + button on the upper right of the window.
Fill in the Name (Mandatory) and choose if it shall be secured (Optional) by using the checkbox on the page.
Click Save.
When the secured option has been selected, the secret key is displayed in a pop-up window and can be copied for later use. The secret key is used to sign the JWT.
For example:
Fabric command: CREATE TOKEN <'token_name'> [SECURED]
. When "SECURED" is used, the secret key is retrieved.
For example:
create token 'Secured1' SECURED;
|Secretkey |
+------------------------------------+
|c55a86d1-9de6-4aaa-bf9e-cedf1391c95b|
If the secured option has not been selected, the token name is used as the token value for the API Key Authentication method.
Web services authentication is done either by user or by API key, where each can be assigned to roles and accordingly to permissions.
Read this article for the list of supported roles, and then click here to learn how to grant permissions to specific roles.