{
"properties":{
"password":{
"title":"Password field",
"description":"A password string",
"type":"string",
"obfuscate":true
}
}
}
Configuring user restrictions to display sensitive information in domain properties
This topic describes what the obfuscate attribute does and describes how to protect which roles are allowed to change the default display domain password properties.
The obfuscate attribute makes credential or sensitive information unintelligible when viewing in REST API output or logs. The default setting in Blue Planet replaces sensitive data in backup files or responses to REST API requests. While it is possible to change the default to unprotect your system output and allow it to display sensitive data in backed up files stored off-site or in API responses, most administrators only want specific users to change the obfuscate property settings.
To learn more about obfuscation, see the Blue Planet Bpocore Developer Guide.
For more details, see these topics:
Requirements
You must be a system administrator to perform these tasks.
If you are a user and see credential data replaced with a long string of asterisks, this is by design. Contact your administrator if you require access to this information.
About obfuscate API changes
A new query argument, obfuscate, is available as a domain API property definition attribute. It has two values: true or false.
-
When obfuscate=true (which is the default), all domain properties marked for obfuscation are replaced in the response with the replacement pattern (twenty asterisks).
-
If obfuscate=false, all domain properties marked for obfuscation by the provider are displayed in clear text in API responses.
For example, if the following definition is contained in a domain provider instance, any REST API requests or backup files with the field password are replaced with the replacement pattern.
If a domain named "myDomain" exists with a password property matching the above properties, a user sending a GET call with the id=myDomain sees the replaced password string property: ******************* in the response body.
Setting user restrictive policies and conditions for obfuscation
|
|
You must be an administrator to complete this task. |
Administrators can have control over which users can hide or unhide sensitive data such as device credentials by defining a policy and setting conditions. To avoid unknown users from switching the protective obfuscate default to allow them to see credentials, admins create a policy that restricts which users can change this attribute default.
There are two ways to define both conditions (the criteria that must be met to enact a policy) and the policy (what to do when the condition is met).
-
At startup time files named policies-00000.json and conditions-0000.json are loaded into the database. You can modify these files to append new policies and conditions, respectively.
-
(Recommended) Use the Policies API to add new policies and the Conditions API to add new conditions.
|
|
There are slight differences in how the data are defined when using each API. These differences are outlined in the developer’s guide. |
To define a policy to restrict what roles are allowed to display credential data using an API request, do any of the following:
-
Use this condition example to allow only administrators to change the obfuscate default:
{ "id" : "63912345-bd8-4249-bd47-818455278571", "name": "role_is_admin", "tenantId": "956345eb-0949-3aa2-8575-72ad9d5f9a61", "description": "Role must be admin", "definition" : "request:obfuscate == false && user:role != \"admin\"" }Append this to the end of the conditions-0000.json file. Substitute the properties to work with your device and tenant IDs.
-
Use this policy example to allow only administrators to change this default GET Domain and GET Domain with ID:
{ "id" : "57fb54a5-4036-4c59-9c3e-37780daadbf4", "policyType": "authorization", "name": "GetDomain", "authRealm": "Market", "tenantId": "956345eb-0949-3aa2-8575-72ad9d5f9a61", "description": "Deny all but admin role from accessing clear text GET Domain Id", "conditionId": "63912345-bdb8-4249-bd47-818455278571", "action": "Deny" }, { "id" : "57fb54a5-4036-4c59-9c3e-37780daadb35", "policyType": "authorization", "name": "ListDomain", "authRealm": "Market", "tenantId": "956345eb-0949-3aa2-8575-72ad9d5f9a61", "description": "Deny all but admin role from accessing clear text on GET Domains", "conditionId": "63912345-bdb8-4249-bd47-818455278571", "action": "Deny" }Append this to the end of the policies-0000.json file. Substitute the properties to work with your device and tenant IDs.
Preventing PUT/PATCH changes to credentials
Blue Planet prevents users from attempting to use any obfuscated values in a PUT or a PATCH call by handling PUT and PATCH calls the following way:
-
If a PUT call contains a replacement pattern as the field value, then Blue Planet uses the original value contained in the database and the field value is ignored.
-
If a PATCH call field contains the exact replacement pattern, the request gets rejected with a 403 error.
-
If an intentional field is desired, you must include fewer or greater asterisk characters to be allowed. So, if a field contains 21 or greater asterisks in a PUT or PATCH call, the field gets accepted. The same would be true of a field containing 19 or fewer asterisks.
Viewing obfuscation in logs
Blue Planet allows administrators to obfuscate log data that may contain HTTP request and response bodies in clear text. The log file, bpocore.restserver.log, is set by default to replace password strings with an asterisk replacement pattern using an obfuscation formatter.
In this release, a combination of using the new obfuscation formatter and a default set of rules results in hidden passwords in the request/response bodies logs.
The formatter is turned on by default (as reflected by use-std-log-formatter = false in com.cyaninc.bpocore.restserver.restserver.settings). If you change this default to true, the standard log formatter allows all password details to appear in clear text.
The obfuscation formatter scans a default set of rules prior to publishing any application/json request or response body to the logs. The rules are defined in the same section using obfuscation-rules.
The default rules are:
obfuscation-rules {
{
field = password
fieldType = string
}
}
These rules search for any string field named password and replaces the contents with the replacement pattern.
You can substitute any field in the obfuscation rules section, but the legal values for fieldType must be "string" or "array". Other values get logged as an error and are ignored.
The following example shows how to obfuscate both password/string and mySecretArray/array:
obfuscation-rules {
{
field = password,
fieldType = string
},
{
field = mySecretArray,
fieldType = array
}
}
In the case of an array, the log replaces entire array with the replacement pattern. For example, an array of strings entitled:
mySecretArray" : [ "secret1", "secret2", "secret3" ], if present in the obfuscation-rules would appear in the logs as:
`mySecretArray" : "*******************".
The following code is an example of what displays in the bpocore.restclient.log. This is one of the two logs that supports obfuscation (the other is bpocore.restserver.log). This example occurs when a user creates a domain with a “password” field.
Entity: {
"id" : "594af36f-1b96-4bc1-9348-cf46ea752ec9",
"title" : "New Domain",
"domainType" : "urn:ciena:bp:domain:rasimulator",
"accessUrl" : "http://192.168.50.4:8080/rasimexample/api/v1",
"properties" : {
"levels" : 1,
"resources_at_level" : [ 3 ],
"password" : "********************"
},
"address" : {
The following code is an example of domain data displayed when a user retrieves it using the GET <domainID> API call with uri parameter, obfuscate = true, and a resourceProvider that defines password as obfuscate=true.
"accessUrl": "http://192.168.50.4:8080/rasimexample/api/v1",
"properties": {
"levels": 1,
"resources_at_level": [
3
],
"password": "********************"
},
"address": {
"city": "",
"zip": "",
"street": "",