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.

note

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

important

• An admin user with the Role: Admin.
• A client with the Role: Realm Role.

note

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:

note

Resource Informations

Name	Value
Requires authentication?	Yes
Rate limited?	No

Request

Request headers

Key	Value
Authorization	Bearer token
Content-Type	application/json

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

1. In the KOBIL AST TMS authenticator in the Action configuration, select the activate option to execute the registration flow.

2. IDP will fetch the device details along with risks from the AST service.

3. The risk value of the device will be evaluated against the configured value in RealmSettings > Risk Bits.

4. If the device has HIGH_RISK, an error screen will be displayed.

5. 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

1. 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.
2. IDP will fetch the device details along with risks from the AST service.
3. The risk value of the device will be evaluated against the configured value in RealmSettings > Risk Bits.
4. If the device has HIGH_RISK, an error screen will be displayed.
5. If the device is risk-free or low-risk, the user will be authenticated on that device.

---