Add Identity (v1.0)

Creates a new Identity AwarenessClosed Check Point Software Blade on a Security Gateway that enforces network access and audits data based on network location, the identity of the user, and the identity of the computer. Acronym: IDA. association for a specified IP address.

POST https://<IP Address or FQDN of Gateway>/_IA_API/v1.0/add-identity

Parameter

Type

Description

Default value

shared-secret

String

Shared secret

N/A

ip-address

String (IP)

Association IP. Supports either IPv4 or IPv6, but not both.

N/A

user

String

User name

Empty string

machine

String

Computer name

Empty string

domain

String

Domain name

Empty string

session-timeout

Integer

Timeout (in seconds) for this Identity Awareness association

43200 (12 hours)

fetch-user-groups

Boolean (0/1)

Defines whether Identity Awareness fetches the user's groups from the user directories defined in SmartConsoleClosed Check Point GUI application used to manage a Check Point environment - configure Security Policies, configure devices, monitor products and events, install updates, and so on..

1

fetch-machine-groups

Boolean (0/1)

Defines whether Identity Awareness fetches the machine's groups from the user directories defined in SmartConsole.

1

user-groups

Array of strings

List of groups, to which the user belongs (when Identity Awareness does not fetch user groups).

Empty array

machine-groups

Array of strings

List of groups, to which the computer belongs (when Identity Awareness does not fetch computer groups).

Empty array

calculate-roles

Boolean (0/1)

Defines whether Identity Awareness calculates the identity's Access Roles.

1

roles

Array of strings

List of roles to assign to this identity (when Identity Awareness does not calculate roles).

Empty array

machine-os

String

Host operating system. For example: Windows 7.

Empty string

host-type

String

Type of host device. For example: Apple iOS device.

Empty string

Parameter

Type

Description

ipv6-address

String (IP)

Created IPv6 identity

ipv4-address

String (IP)

Created IPv4 identity

message

String

Textual description of the command's result

Best Practice - You must include the domain name whenever available, to make sure that the user is authorized by the correct server, improves performance and prevents incorrect authorization, when there are identical user names in more than one domain.

Notes

  • The request must include user or computer information or both. The shared-secret and ip-address fields are mandatory.

  • String attributes, for example, user, domain and group names, must not contain curly brackets ("{", "}"), square brackets ("[", "]"), or angle brackets ("<", ">"). Requests that contain these characters fail.

  • When you set fetch-user-groups or fetch-machine-groups or both to 1, you must in addition set calculate-roles to 1. If not, there is no assignment of Access Roles and the request fails.

  • When you set fetch-user-groups or fetch-machine-groups or both to 1, user authorization can fail (for example, if the user cannot be found in an Account Unit). Because the gateway sends the response before the authorization process is complete, a successful response does not necessarily mean the gateway created the identity successfully.

  • If you know the operating system and host type of the created associations, you can include this information in the machine-os and host-type fields. This improves the information audit, but does not harm enforcement.

  • For Active Directory user and computer groups, which are generated with the Access RoleClosed Access Role objects let you configure network access according to: Networks, Users and user groups, Computers and computer groups, Remote Access Clients. After you activate the Identity Awareness Software Blade, you can create Access Role objects and use them in the Source and Destination columns of Access Control Policy rules. creation tool, include a special prefix:

    • Group prefix is ad_group_

    • User prefix is ad_user_

    • Machine prefix is ad_machine_

    For example, for Active Directory user group MyGroup the user group attribute is ad_group_MyGroup. For computer group MyMachinePC, the machine-groups attribute is ad_machine_MyMachinePC.

Example 1 - Minimum request for user identity generation

Request

POST https://gw.acme.com/_IA_API/v1.0/add-identity 

{
 "shared-secret":"****",
 "ip-address":"1.2.3.5",
 "user":"mary"
}

Response

{
 "ipv4-address":"1.2.3.5",
 "message":"Association sent to PDP."
}

Example 2- User-defined groups, calculate roles

Request

POST https://gw.acme.com/_IA_API/v1.0/add-identity 

{
 "shared-secret":"****",
 "ip-address":"1.1.1.1",
 "user":"john", 
 machine":"",
 "domain":"cme.com",
 "user-groups":["MyUserGroup"],
 "roles":[],"timeout":4,
 "fetch-user-groups":0,
 "calculate-roles":1,
 "identity-source":"ACME API Client"
}

Response

{
 "ipv4-address":"1.1.1.1",
 "message":"Association sent to PDP."
}

Example 3 - User-defined groups and roles, detailed information

Request

POST https://gw.acme.com/_IA_API/v1.0/add-identity 

{
 "shared-secret":"****",
 "user":"John",
 "machine":"Laptop_1234",
 "ip-address":"2.2.2.2",
 "identity-source":"ACME API Client",
 "machine-os":"Windows 10 (Build 1176)",
 "host-type":"Laptop",
 "fetch-user-groups":0,
 "fetch-machine-groups":0,
 "calculate-roles":0,
 "session-timeout":43200,
 "user-groups":["EnterpriseFinanceUsers","ad_user_JohnDoe"],
 "machine-groups":["EnterpriseLaptopMachines"],
 "roles":["FinanceUser","StandardLaptop"]
}

Response

{
 "ipv4-address" : "2.2.2.2",
 "message" : "Association sent to PDP."
}