Add Identity (v1.0)

Description

Creates a new Identity Awareness association for a specified IP address.

Syntax

POST https://<Gateway_IP_or_FQDN>/_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 SmartConsole.	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

Response

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. This ensures 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 such as user, domain and group names, must not contain curly brackets ("{", "}"), square brackets ("[", "]"), or angle brackets ("<", ">"). Requests containing such characters will fail.
When you set fetch-user-groups or fetch-machine-groups or both to 1, you must also set calculate-roles to 1. Otherwise, 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 auditing information, but does not affect enforcement.
For active directory user and computer groups, which are generated with the Access Role 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.

Examples

Example request 1: Minimum request for user identity generation

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

{

"shared-secret":"****",

"ip-address":"1.2.3.5",

"user":"mary",

}

Response 1

{

"ipv4-address":"1.2.3.5",

"message":"Association sent to PDP."

}

Example request 2: User-defined groups, calculate roles

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":43200,

"fetch-user-groups":0,

"calculate-roles":1,

"identity-source":"ACME API Client"

}

Response 2

{

"ipv4-address":"1.1.1.1",

"message":"Association sent to PDP."

}

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

{

"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 3

{

"ipv4-address" : "2.2.2.2",

"message" : "Association sent to PDP."

}