Device Security Policy
RISK BITS
Risk Bits plays a fundamental role in device security. These vital components are actively engaged in evaluating the risk level associated with the currently used device, thereby serving as a defense mechanism for preserving the integrity and confidentiality of data.
Risk Bits is a component within the realm settings of the KOBIL IAM system.
Go to > Realm settings > Click on the Risk Bits.
We should check the box, to execute Risk Bits in the flow.
Using APIs the Risk Bits can be created, edited and deleted in the following tabular box, which is displayed below.
Configuration | Description |
---|---|
Rating level | Assessing the Risk Level on the device. |
Score | Scoring level for the risks. |
Risk | Rate of the risks. |
Risk Details Android | Android risk name which is present in the device. |
Risk Details iOS | iOS risk name which is present in the device. |
Operation | Device execution is determined by the risk operation. For instance, if the JBreak[1] (40001) is the Risk name of the device in 'Risk Details iOS' is 'HIGH_RISK', in Operation the device will not be allowed. |
The ability to adjust the acceptable level of risk associated with a particular device platform. Every device have a risk score based on various factors, such as its security settings.
Example for riskbits execution:
-
If a user's device satisfies the specified conditions, meaning it has a risk level corresponding to "Jbreak [400]" and is an iOS device, it is granted permission based on
Operation
to execute a particular flow or task. -
This allows users with compatible devices to perform certain actions as defined.
KOBIL Device Risk Policies
The KOBIL MC SDK collects device security information and transmits it to the KOBIL Shift backend each time the app connects online. The KOBIL IDP permits us to configure the access restriction based on device risk, empowering the system to make decision on granting or denying access.
IDP provides two components to ensure the risk analysis
Risk Bits APIs
APIs serve as versatile tools within the system, enabling users to perform a range of actions, including creating, modifying, deleting, and verifying the risk associated with a device.
KOBIL Risk and Policy Evaluator Authenticator
The authenticator verify the risk linked to the device. Then it determines whether to allow or deny access, considering predefined criteria and established security measures in the IDP.
APIs required for Risk Bits Execution
- An admin user with the Role: Admin.
- A client with the Role: Realm Role.
API requests must be made over https. Calls made over plain http will fail.
- Initiate the steps by getting the access token, which is authorised by the IDP.
Get Access Token:
The Get Access Token API serves the purpose of obtaining an authentication token that is essential for the authorization process. This API facilitates the acquisition of the necessary token to grant authorization for specific actions or services.
Access token requirements: Username, Password along with ClientID is required to get the Access Token.
Request headers
Key | Value |
---|---|
Content-Type | application/x-www-form-urlencoded |
HTTP request
POST https://{tenantId}.{hostname}/auth/realms/{tenantId}/protocol/openid-connect/token
Request body (*Required)
Parameter Name | Type | Description |
---|---|---|
grant_type* | String | The grant type should be password . |
username* | String | The username for which the token needs to be generated. |
password* | String | Password corresponding to the username. |
client_id* | String | The Client ID for which the access token is to be generated. |
client_secret | String | Secret corresponding to the given clientID. Secret will be available only for the clients with access type selected confidential during client creation. This is an optional parameter. |
curl --location --request POST 'https://{tenantId}.{hostname}/auth/realms/{tenantId}/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=testuser' \
--data-urlencode 'password=abc123' \
--data-urlencode 'client_id=demo' \
--data-urlencode 'client_secret=4d759a23-e01d-4902-8727-98'
Response
Parameter Name | Type | Description |
---|---|---|
access_token | String | The newly created access token. |
expires_in | Integer | Validity of the access token in seconds. |
refresh_expires_in | Integer | Validity of the refresh token in seconds. |
refresh_token | String | The new refresh token. |
token_type | String | Indicates access token type. |
not-before-policy | Integer | not-before policy ensures that any tokens issued before that time become invalid. |
session_state | Integer | The Client ID salted cryptographic hash, the root URL, and the browser state are all included in the session state value. Basically session_state value is used to monitor end user sessions. |
scope | String | The scope requested for the token. |
Sample Response
{
"access_token": String,
"expires_in": Integer,
"refresh_expires_in": Integer,
"refresh_token": String,
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": String,
"scope": String
}
Response Status Information
Status Code | Status | Message |
---|---|---|
200 | OK | OK |
400 | Bad Request | Unsupported grant_type |
400 | Bad Request | Invalid client credentials |
401 | Unauthorized | Invalid user credentials |
401 | Unauthorized | Invalid client secret |
404 | Not Found | Realm does not exist |
How to use the access token?
-
After successful authentication, the Get Access Token API will provide an access token.
-
To ensure authentication for Risk bits API requests, it is essential that the access token is included in the API requests.
-
This can be achieved by incorporating the access token into the HTTP Authorization header in the following format:
Bearer <token>
.
Risk Bits APIs:
Add List of Riskbits:
The Add List of Riskbits API facilitates the integration of riskbits into a list, in accordance with the information provided in the request.
HTTP request URL for SHIFT
POST https://{hostname}/auth/realms/{tenantId}/kobilriskbits/resources-auth/list
Request body (*Required)
Field Name | Type | Description |
---|
- ratingLevel | String | Rating level of risk
- score | String | Mention the score level for risk.
- risk | String | Risk name. riskAndroid | String | Android risk name. riskIOS | String | iOS risk name.
- operation | String | Risk operation name realmId | String | Tenant name
Sample Request
[
{
"ratingLevel" : "A",
"score":"986-999",
"risk" :"0.80",
"riskAndroid":"",
"riskIOS":"",
"operation":"OK",
"realmId": "XXX_demo"
},{
"ratingLevel" : "E",
"score":"949-961",
"risk" :"4.38",
"riskAndroid":"JBreak",
"riskIOS":"JBreak",
"operation":"OK",
"realmId": "XXX_demo1"
}
]
Response Status Information
Status Code | Status | Message |
---|---|---|
200 | OK | Successfully added. |
401 | Unauthorized | HTTP 401 Unauthorized. |
409 | Conflict | Already exist. |
Add Or Update Riskbits Status:
The Add or Update Riskbits Status functionality is a feature that allows users to modify and manage the status of individual risk bits within a system or application.
HTTP request URL for SHIFT
POST https://{hostname}/auth/realms/{tenantId}/kobilriskbits/resources-auth/list
Request body (*Required)
Field Name | Type | Description |
---|
- ratingLevel | String | Rating level of risk
- score | String | Mention the score level for risk.
- risk | String | Risk name. riskAndroid | String | Android risk name. riskIOS | String | iOS risk name.
- operation | String | Risk operation name realmId | String | Tenant name
Sample Request
[
{
"ratingLevel" : "A",
"score":"986-999",
"risk" :"0.80",
"riskAndroid":"",
"riskIOS":"",
"operation":"OK",
"realmId": "XXX_demo"
},{
"ratingLevel" : "E",
"score":"949-961",
"risk" :"4.38",
"riskAndroid":"JBreak",
"riskIOS":"JBreak",
"operation":"OK",
"realmId": "XXX_demo1"
}
]
Response Status Information
Status Code | Status | Message |
---|---|---|
200 | OK | Successfully added. |
401 | Unauthorized | HTTP 401 Unauthorized. |
409 | Conflict | Already exist. |
Get Riskbits Status:
The Get Riskbits Status feature is designed to provide users with information about the current status of specific risk bits within a system or application.
HTTP request URL for SHIFT
GET https://{hostname}/auth/realms/{tenantId}/kobilriskbitstatus/resources-auth
Response
Field Name | Type | Description |
---|---|---|
id | String | Id of the risk |
realmId | String | Tenant name |
enabled | String | Enabled status |
Sample Response
{
"id": "929f0a33-3434-48f6-b735-5eb055835945",
"realmId": "xxxtenant",
"enabled": true
}
Response Status Information
Status Code | Status | Message |
---|---|---|
200 | OK | Successfully created. |
204 | No Content | No Content. |
401 | Unauthorized | HTTP 401 Unauthorized. |
Get Riskbits:
The Get Riskbits functionality is a feature that allows users to retrieve information about specific risk bits within a system or application.
HTTP request URL for SHIFT
GET https://{hostname}/auth/realms/{tenantId}/kobilriskbits/resources-auth/{riskbitid}
Response
Field Name | Type | Description |
---|---|---|
id | String | Unique riskbitId |
ratingLevel | String | Rating level of risk |
score | String | Score of the risk. |
risk | String | Risk name. |
riskAndroid | String | Android risk name. |
riskIOS | String | iOS risk name. |
operation | String | Risk operation name |
realmId | String | Tenant name |
Sample Response
{
"id": "fa8975fc-a3b6-42f4-85d6-1107ec5fe864",
"ratingLevel": "A",
"score": "986-999",
"risk": "0.80",
"riskAndroid": "",
"riskIOS": "",
"operation": "none",
"realmId": "demokc"
}
Response Status Information
Status Code | Status | Message |
---|---|---|
200 | OK | Successfully created. |
204 | No Content | No Content. |
401 | Unauthorized | HTTP 401 Unauthorized. |
Create Riskbits
Using this API, riskbits can be added or created as provided in the request.
HTTP request URL for SHIFT
POST https://{hostname}/auth/realms/{tenantId}/kobilriskbits/resources-auth
Request body (*Required)
Field Name | Type | Description |
---|
- ratingLevel | String | Assessing the Risk Level on the device.|
- score | String | Mention the score level for risk in the device.|
- risk | String |Rate of the risks.| riskAndroid | String | Android risk name which is present in the device.| riskIOS | String | iOS risk name which is present in the device.|
- operation | String | Device execution is determined by the risk operation. For instance, if the JBreak[1]40001 is the Risk name of the device in 'Risk Details iOS' is 'HIGH_RISK,'in
Operation
the device will not be allowed.| realmId | String | Tenant name which is present in the device.|
Sample Request
{
"ratingLevel" : "L",
"score":"1-491",
"risk" :"60.45",
"riskAndroid":"CodeInjection",
"riskIOS":"CodeInjection",
"operation":"HIGH_RISK",
"realmId":"xxxtenant"
}
Response
Status Code | Status | Description |
---|---|---|
201 | Created | Successfully created |
409 | Conflict | Riskbit already exists |
401 | Unauthorized | HTTP 401 Unauthorized |
Verify Device Risk
Using this API will verify the device risk.
HTTP request URL for SHIFT
POST https://{hostname}/auth/realms/{tenantId}/kobilriskbits/resources-auth/verify
Request body
Field Name | Type | Description |
---|---|---|
riskName | String | Name of the risk |
platform | String | Mention the platform |
Sample Request
{
"riskName" : "JBreak",
"platform" : "ios"
}
Response
Field Name | Type | Description |
---|---|---|
id | String | Unique identifier for each riskbit, providing a distinct reference for tracking and managing individual instances of risk within a system. |
ratingLevel | String | The "ratingLevel" field indicates the categorization or classification of the risk's severity. |
score | String | Qualitative measure that quantifies the magnitude or degree of the risk. |
risk | String | Rate of the risks. |
riskAndroid | String | The "riskAndroid" field pertains specifically to the name. |
riskIOS | String | The "riskIOS" field pertains specifically to the name. |
operation | String | Device execution is determined by the risk operation. For instance, if the JBreak[1]40001 is the Risk name of the device in 'Risk Details iOS' is 'HIGH_RISK,'in Operation the device will not be allowed. |
realmId | String | The "realmId" field serves as an identifier for a specific tenant, entity, or organizational unit within a system. |
Sample Response
[
{
"id": "34db8eb9-c1c4-4f14-a258-91eb9b9c37bf",
"ratingLevel": "E",
"score": "949-961",
"risk": "4.38",
"riskAndroid": "JBreak",
"riskIOS": "JBreak",
"operation": "OK",
"realmId": "demokc"
}
]
Response Status Information
Status Code | Status | Message |
---|---|---|
200 | OK | Successfully created |
401 | Unauthorized | HTTP 401 Unauthorized |
Delete All Riskbits
Using this API, riskbits which are added using Add List of Riskbits will be removed/deleted.
HTTP request URL for SHIFT
DELETE https://{hostname}/auth/realms/{tenantId}/kobilriskbits/resources-auth
Response
Status Code |Status | Description |:-----|:------| 202 | OK | All Riskbits Deleted Successfull 404| Not Found| The requested resource could not be found
KOBIL Risk and Policy Evaluator Authenticator
The KOBIL Risk and Policy Evaluator Authenticator can be employed to assess the risk associated with a user's device during both the registration and login procedures.
KOBIL Risk and Policy Evaluator Authenticator for Registration flow
The main task of this flow is to is to assess the risk linked to the user's device during the registration of the device.
Execution Flow
-
In the KOBIL AST TMS authenticator in the
Action
configuration, select theactivate
option to execute the registration flow. -
IDP will fetch the device details along with risks from the AST service.
-
The risk value of the device will be evaluated against the configured value in RealmSettings > Risk Bits.
-
If the device has HIGH_RISK, an error screen will be displayed.
-
If the device is risk-free or low-risk, the user will be registered against the device.
KOBIL Risk and Policy Evaluator Authenticator for Login execution
The main task of this flow is to evaluate the risk associated with the user's device during the login process.
Execution Flow
- The KOBIL Risk and Policy Evaluator can be executed after the 1FA authenticators to verify the risk of the device. For instance, KOBIL Username Password Form authenticator is used to identify the user along with AST Login authenticator to fetch the device details.
- IDP will fetch the device details along with risks from the AST service.
- The risk value of the device will be evaluated against the configured value in RealmSettings > Risk Bits.
- If the device has HIGH_RISK, an error screen will be displayed.
- If the device is risk-free or low-risk, the user will be authenticated on that device.