Skip to main content

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.

Realm settings

We should check the box, to execute Risk Bits in the flow.

Execute riskbits

Using APIs the Risk Bits can be created, edited and deleted in the following tabular box, which is displayed below.

Risk Bits tabular

ConfigurationDescription
Rating levelAssessing the Risk Level on the device.
ScoreScoring level for the risks.
RiskRate of the risks.
Risk Details AndroidAndroid risk name which is present in the device.
Risk Details iOSiOS risk name which is present in the device.
OperationDevice 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

KeyValue
Content-Typeapplication/x-www-form-urlencoded

HTTP request

POST https://{tenantId}.{hostname}/auth/realms/{tenantId}/protocol/openid-connect/token

Request body (*Required)

Parameter NameTypeDescription
grant_type*StringThe grant type should be password.
username*StringThe username for which the token needs to be generated.
password*StringPassword corresponding to the username.
client_id*StringThe Client ID for which the access token is to be generated.
client_secretStringSecret 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 NameTypeDescription
access_tokenStringThe newly created access token.
expires_inIntegerValidity of the access token in seconds.
refresh_expires_inIntegerValidity of the refresh token in seconds.
refresh_tokenStringThe new refresh token.
token_typeStringIndicates access token type.
not-before-policyIntegernot-before policy ensures that any tokens issued before that time become invalid.
session_stateIntegerThe 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.
scopeStringThe 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 CodeStatusMessage
200OKOK
400Bad RequestUnsupported grant_type
400Bad RequestInvalid client credentials
401UnauthorizedInvalid user credentials
401UnauthorizedInvalid client secret
404Not FoundRealm 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

NameValue
Requires authentication?Yes
Rate limited?No

Request

Request headers

KeyValue
AuthorizationBearer token
Content-Typeapplication/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 NameTypeDescription
  • 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 CodeStatusMessage
200OKSuccessfully added.
401UnauthorizedHTTP 401 Unauthorized.
409ConflictAlready 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 NameTypeDescription
  • 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 CodeStatusMessage
200OKSuccessfully added.
401UnauthorizedHTTP 401 Unauthorized.
409ConflictAlready 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 NameTypeDescription
idStringId of the risk
realmIdStringTenant name
enabledStringEnabled status

Sample Response

{
"id": "929f0a33-3434-48f6-b735-5eb055835945",
"realmId": "xxxtenant",
"enabled": true
}

Response Status Information

Status CodeStatusMessage
200OKSuccessfully created.
204No ContentNo Content.
401UnauthorizedHTTP 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 NameTypeDescription
idStringUnique riskbitId
ratingLevelStringRating level of risk
scoreStringScore of the risk.
riskStringRisk name.
riskAndroidStringAndroid risk name.
riskIOSStringiOS risk name.
operationStringRisk operation name
realmIdStringTenant 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 CodeStatusMessage
200OKSuccessfully created.
204No ContentNo Content.
401UnauthorizedHTTP 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 NameTypeDescription
  • 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 CodeStatusDescription
201CreatedSuccessfully created
409ConflictRiskbit already exists
401UnauthorizedHTTP 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 NameTypeDescription
riskNameStringName of the risk
platformStringMention the platform

Sample Request

{
"riskName" : "JBreak",
"platform" : "ios"
}

Response

Field NameTypeDescription
idStringUnique identifier for each riskbit, providing a distinct reference for tracking and managing individual instances of risk within a system.
ratingLevelStringThe "ratingLevel" field indicates the categorization or classification of the risk's severity.
scoreStringQualitative measure that quantifies the magnitude or degree of the risk.
riskStringRate of the risks.
riskAndroidStringThe "riskAndroid" field pertains specifically to the name.
riskIOSStringThe "riskIOS" field pertains specifically to the name.
operationStringDevice 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.
realmIdStringThe "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 CodeStatusMessage
200OKSuccessfully created
401UnauthorizedHTTP 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.

KOBIL Risk and Policy Evaluator registration flow

Execution Flow

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

  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

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.

KOBIL Risk and Policy Evaluator Authenticator

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.
KOBIL Risk and Policy Evaluator