How To Use The Associations Functions - TheJumpCloud/support GitHub Wiki

What is a JumpCloud object?
What Are Associations?
- Direct Associations
- Indirect Associations
Using Get-JCAssociation

What is a JumpCloud object?

Any discrete item within a JumpCloud tenant is a JumpCloud object with a unique JumpCloud id.

JumpCloud object can be of the following types: application, command, g_suite, ldap_server, office_365, policy, radius_server, system_group, system, user_group, user, directory.

As a JumpCloud tenant is configured objects are created.

Typically, object types are what you see on the left-hand pane of the admin console; where as a specific object is what you see in the main page of the admin console after you click on the object type.

Example Object

What Are Associations?

An association is when you create a link between one JumpCloud object to another JumpCloud object. By default, when an object is created in JumpCloud it is created without any associations. An association can be configured and represented by using the checkboxes within the JumpCloud admin console. Checking the box then creates an association between the two object's ids, which can then traverse to other objects.

There are two types of associations. Objects can be associated either directly or indirectly with one another.

Direct Associations

Direct associations are a one-to-one relationship between two objects in JumpCloud.

In the JumpCloud admin console a direct link between two objects occurs when a checkbox is selected and then saved on an object which then associates it directly with the target object.

Direct Checkbox

Bryan Alders, Am Anemali, and Adam Ant are all directly associated with the user group "New User Group".

Indirect Associations

Indirect associations are a one-to-many relationship between the individual members of a JumpCloud group and the objects that are directly bound to a group.

Indirect associations allow members of JumpCloud groups to inherit attributes from their parent and to become indirectly associated with all the direct associations of that group.

Indirect associations can be used to map a system to a JumpCloud system_group, user_group, command, or policy.

Indirect associations can be used to map a user to a JumpCloud user_group, system_ group, application, directory, or radius_server.

Because a JumpCloud user_group and system_group can be associated directly to one another indirect associations can span more than one object.

EXAMPLE: "user" -> "user_group" -> "system_group" -> "system" EXAMPLE: "system" -> "system_group" -> "user_group" -> "user"

In the JumpCloud admin console indirect associations are represented by obfuscated checkboxes.

Indirect Checkbox

Christopher Froome, Steve Prefontaine, ldap service, and Jens Voit are all indirectly associated with JumpCloud LDAP. Admin user is directly associated with JumpCloud LDAP. An obfuscated checkbox represents an indirect association.

Using Get-JCAssociation

The function Get-JCAssociation can be used to query an object’s associations and then provide information about how objects are associated with one another.

Get-JCAssociation Input

Parameter Name	Description	IsMandatory	Aliases	ParameterType
`-Type`	The type of the object.	Yes		`string`
`-Id`	The unique id of the object.	Yes	`_id`	`string[]`
`-Name`	The name of the object.	Yes	`domain`, `displayName`, `username`	`string[]`
`-TargetType`	The target object type.	Yes		`string[]`
`-Direct`	Returns only "Direct" associations.	No		`switch`
`-Indirect`	Returns only "Indirect" associations.	No		`switch`
`-IncludeInfo`	Appends "Info" and "TargetInfo" properties to output.	No		`switch`
`-IncludeNames`	Appends "Name" and "TargetName" properties to output.	No		`switch`
`-IncludeVisualPath`	Appends "visualPathById", "visualPathByName", and "visualPathByType" properties to output.	No		`switch`

Get-JCAssociation Output

Default Output

The default output of the Get-JCAssociation command will return a formatted object that includes all associations for a given input object.

Get-JCAssociation -Type:system -Id:5c9a95f84tdo1376318g5148


action          : get
associationType : direct
id              : 5c9a95f84tdo1376318g5148
type            : system
targetId        : 5c75cbcebfe8c0429a816d56
targetType      : user
paths           : {System.Object[]}

action             : get
associationType    : indirect
id                 : 5c9a95f84tdo1376318g5148
type               : system
targetId           : 5c75d403ee8df27f82a8051a
targetType         : user
compiledAttributes : @{ldapGroups=System.Object[]}
paths              : {  }

action          : get
associationType : direct
id              : 5c9a95f84tdo1376318g5148
type            : system
targetId        : 5c8a81131f24752158a420a4
targetType      : system_group
paths           : {System.Object[]}

This object by default will return seven fields.

Field Name	Description
action	Describes the action the command is executing. Get-JCAssociation will always return `Get`
associationType	Returns indirect or direct
id	The JumpCloud id for the input object
type	The type of the input object
targetId	The JumpCloud id of the associated target object
targetType	The type of the associated target object
compiledAttributes	Attributes (if any) of the associated target object
paths	The path(s) to the target object

Specify Object Type

When using Get-JCAssocitaion you must specify an object type.

JumpCloud object can be of the following types: application, command, g_suite, ldap_server, office_365, policy, radius_server, system_group, system, user_group, user, directory.

After an object type is specified a name or id value must be entered to identify the object to query.

Specify Object Name

Get-JCAssociation -Type:user_group -Name:employee

This example will return all the associations for the user group "employee"

Note that if -Type:user is specified the alias -username is created for the -name property and can be used instead of -name.

Get-JCAssociation -Type:user -username:holly.flax

This example will return all the associations for the user with username "holly.flax"

Note that if -Type:system is specified the alias -displayName is created for the -name property and can be used instead of -name.

Get-JCAssociation -Type:system -displayName:Hollys-Mac

This example will return all the associations for the system with displayName "Hollys-Mac"

The field displayName is not enforced as a unique field for systems in JumpCloud. A warning will appear if a specified -name value returns more then one record.

 Get-JCAssociation -Type:system -displayName:admins-mac.local
WARNING: Found "4" "system" with the "name" of "admins-mac.local"

Specify Object Id

An object id value can be used to query associations as an alternative to searching by an objects name.

id values are always unique values that resolve to a single object within JumpCloud.

Get-JCAssociation -Type:system -Id:5c9o95o84lbe1376318an1s8

This example will return all the associations for the system with an id value of "5c9o95o84lbe1376318an1s8"

Get-JCAssociation -Type:user -Id:5c9o95o84lbo1376318ot1s8

This example will return all the associations for the user with an id value of "5c9o95o84lbo1376318ot1s8"

Get-JCAssociation -Direct Parameter

The -Direct switch parameter can be used with the Get-JCAssociations command to only output direct associations.

Get-JCAssociation -Indirect Parameter

The -Indirect switch parameter can be used with the Get-JCAssociations command to only output indirect associations.

Get-JCAssociation -TargetType Parameter

The -TargetType parameter can be used with the Get-JCAssociations command to only search for specific associates of a given targetType.

Get-JCAssociation -Type:system -Id:5c9b95f84cbd1376318c5148 -TargetType system_group


action          : get
associationType : direct
id              : 5c9b95f84cbd1376318c5148
type            : system
targetId        : 5c8a81131f24752158a420a4
targetType      : system_group
paths           : {System.Object[]}

This example will return all the system_group associations for the system with an id value of "5c9b95f84cbd1376318c5148"

Get-JCAssociation -IncludeNames Parameter

The -IncludeNames switch parameter can be used with the Get-JCAssociations command to include the names of objects in the formatted output.

Adding the -IncludeNames increases the number of API requests the Get-JCAssociations command runs which will increase the time it takes to gather the results of the command.

Get-JCAssociation -Type:system -Id:5c9b95f84cbd1376318c5148 -IncludeNames

action          : get
associationType : direct
id              : 5c9b95f84cbd1376318c5148
name            : Holly-Flax-Mac.local
type            : system
targetId        : 5c75cbcebfe8c0429a816d56
targetName      : holly.flax
targetType      : user
paths           : {System.Object[]}

action             : get
associationType    : indirect
id                 : 5c9b95f84cbd1376318c5148
name               : Holly-Flax-Mac.local
type               : system
targetId           : 5c75d403ee8df27f82a8051a
targetName         : jcadmin
targetType         : user
compiledAttributes : @{ldapGroups=System.Object[]}
paths              : {  }

action          : get
associationType : direct
id              : 5c9b95f84cbd1376318c5148
name            : Holly-Flax-Mac.local
type            : system
targetId        : 5c8a81131f24752158a420a4
targetName      : All Systems
targetType      : system_group
paths           : {System.Object[]}

Including the parameter -IncludeNames adds name and targetName to the output of Get-JCAssociation

Get-JCAssociation -IncludeVisualPath Parameter

The -IncludeVisualPath switch parameter can be used with the Get-JCAssociations command to include output which represents a visual depiction of associations in the formatted output.

Adding the -IncludeVisualPath increases the number of API requests the Get-JCAssociations command runs which will increase the time it takes to gather the results of the command.

Get-JCAssociation -Type:system -Id:5c9b95f84cbd1376318c5148 -IncludeVisualPath

action           : get
associationType  : direct
id               : 5c9b95f84cbd1376318c5148
type             : system
targetId         : 5c75cbcebfe8c0429a816d56
targetType       : user
visualPathById   : "5c9b95f84cbd1376318c5148" -> "5c75cbcebfe8c0429a816d56"
visualPathByName : "Holly-Flax-Mac.local" -> "holly.flax"
visualPathByType : "system" -> "user"
paths            : {System.Object[]}

action             : get
associationType    : indirect
id                 : 5c9b95f84cbd1376318c5148
type               : system
targetId           : 5c75d403ee8df27f82a8051a
targetType         : user
visualPathById     : "5c9b95f84cbd1376318c5148" -> "5c8a81131f24752158a420a4" -> "5c8a8103232e1164e95c7abc" -> 
                     "5c75d403ee8df27f82a8051a"
visualPathByName   : "Holly-Flax-Mac.local" -> "All Systems" -> "Default Admin" -> "jcadmin"
visualPathByType   : "system" -> "system_group" -> "user_group" -> "user"
compiledAttributes : @{ldapGroups=System.Object[]}
paths              : {  }

action           : get
associationType  : direct
id               : 5c9b95f84cbd1376318c5148
type             : system
targetId         : 5c8a81131f24752158a420a4
targetType       : system_group
visualPathById   : "5c9b95f84cbd1376318c5148" -> "5c8a81131f24752158a420a4"
visualPathByName : "Holly-Flax-Mac.local" -> "All Systems"
visualPathByType : "system" -> "system_group"
paths            : {System.Object[]}

Get-JCAssociation -IncludeInfo Parameter

The -IncludeInfo switch parameter can be used with the Get-JCAssociations command to include output that contains all attributes of the input and target objects in the formatted output.

Adding the -IncludeInfo increases the number of API requests the Get-JCAssociations command runs which will increase the time it takes to gather the results of the command.

Get-JCAssociation -Type:system -Id:5c9b95f84cbd1376318c5148 -IncludeInfo


action          : get
associationType : direct
id              : 5c9b95f84cbd1376318c5148
type            : system
info            : @{organization=5c71807298ce437512b9e8b7; created=3/27/19 3:25:44 PM; lastContact=3/27/19 11:31:22 
                  PM; os=Mac OS X; version=10.14; arch=x86_64; networkInterfaces=System.Object[]; 
                  hostname=Holly-Flax-Mac.local; displayName=Holly-Flax-Mac.local; systemTimezone=-600; 
                  templateName=macosx-darwin-x86_64; remoteIP=80.87.24.84; active=False; sshdParams=System.Object[]; 
                  allowSshPasswordAuthentication=False; allowSshRootLogin=False; 
                  allowMultiFactorAuthentication=False; allowPublicKeyAuthentication=False; modifySSHDConfig=False; 
                  agentVersion=0.10.53; connectionHistory=System.Object[]; sshRootEnabled=True; 
                  id=5c9b95f84cbd1376318c5148; _id=5c9b95f84cbd1376318c5148; serialNumber=VMqYxmXmp3io; ById=_id; 
                  ByName=displayName; TypeName=; TypeNameSingular=system; TypeNamePlural=systems; 
                  Targets=System.Object[]; TargetSingular=System.Object[]; TargetPlural=System.Object[]}
targetId        : 5c75cbcebfe8c0429a816d56
targetType      : user
targetInfo      : @{account_locked=False; activated=True; addresses=System.Object[]; allow_public_key=True; 
                  attributes=System.Object[]; company=Dunder Mifflin; costCenter=Scranton; department=Corporate; 
                  description=; displayname=Holly Flax; [email protected]; employeeType=Corporate; 
                  enable_managed_uid=False; enable_user_portal_multifactor=False; externally_managed=False; 
                  firstname=Holly; jobTitle=HR Execuative; lastname=Flax; ldap_binding_user=False; location=WFH; 
                  mfa=; middlename=; password_never_expires=False; passwordless_sudo=False; 
                  phoneNumbers=System.Object[]; samba_service_user=False; ssh_keys=System.Object[]; sudo=False; 
                  unix_guid=5029; unix_uid=5029; username=holly.flax; created=2/26/19 11:29:18 PM; 
                  password_expiration_date=7/15/19 7:15:07 AM; password_expired=False; totp_enabled=False; 
                  _id=5c75cbcebfe8c0429a816d56; id=5c75cbcebfe8c0429a816d56; ById=_id; ByName=username; TypeName=; 
                  TypeNameSingular=user; TypeNamePlural=users; Targets=System.Object[]; 
                  TargetSingular=System.Object[]; TargetPlural=System.Object[]}
paths           : {System.Object[]}

action             : get
associationType    : indirect
id                 : 5c9b95f84cbd1376318c5148
type               : system
info               : @{organization=5c71807298ce437512b9e8b7; created=3/27/19 3:25:44 PM; lastContact=3/27/19 
                     11:31:22 PM; os=Mac OS X; version=10.14; arch=x86_64; networkInterfaces=System.Object[]; 
                     hostname=Holly-Flax-Mac.local; displayName=Holly-Flax-Mac.local; systemTimezone=-600; 
                     templateName=macosx-darwin-x86_64; remoteIP=80.87.24.84; active=False; 
                     sshdParams=System.Object[]; allowSshPasswordAuthentication=False; allowSshRootLogin=False; 
                     allowMultiFactorAuthentication=False; allowPublicKeyAuthentication=False; 
                     modifySSHDConfig=False; agentVersion=0.10.53; connectionHistory=System.Object[]; 
                     sshRootEnabled=True; id=5c9b95f84cbd1376318c5148; _id=5c9b95f84cbd1376318c5148; 
                     serialNumber=VMqYxmXmp3io; ById=_id; ByName=displayName; TypeName=; TypeNameSingular=system; 
                     TypeNamePlural=systems; Targets=System.Object[]; TargetSingular=System.Object[]; 
                     TargetPlural=System.Object[]}
targetId           : 5c75d403ee8df27f82a8051a
targetType         : user
targetInfo         : @{account_locked=False; activated=True; addresses=System.Object[]; allow_public_key=True; 
                     attributes=System.Object[]; company=Dunder Mifflin; costCenter=Scranton; department=Operations; 
                     description=; displayname=; [email protected]; employeeType=Salaried; 
                     enable_managed_uid=False; enable_user_portal_multifactor=False; externally_managed=False; 
                     firstname=Default; jobTitle=Office Administrator; lastname=Admin; ldap_binding_user=False; 
                     location=WFH; mfa=; middlename=; password_never_expires=False; passwordless_sudo=False; 
                     phoneNumbers=System.Object[]; samba_service_user=False; ssh_keys=System.Object[]; sudo=True; 
                     unix_guid=5045; unix_uid=5045; username=jcadmin; created=2/27/19 12:04:19 AM; 
                     password_expiration_date=7/14/19 1:22:16 AM; password_expired=False; totp_enabled=False; 
                     _id=5c75d403ee8df27f82a8051a; id=5c75d403ee8df27f82a8051a; ById=_id; ByName=username; 
                     TypeName=; TypeNameSingular=user; TypeNamePlural=users; Targets=System.Object[]; 
                     TargetSingular=System.Object[]; TargetPlural=System.Object[]}
compiledAttributes : @{ldapGroups=System.Object[]}
paths              : {  }

action          : get
associationType : direct
id              : 5c9b95f84cbd1376318c5148
type            : system
info            : @{organization=5c71807298ce437512b9e8b7; created=3/27/19 3:25:44 PM; lastContact=3/27/19 11:31:22 
                  PM; os=Mac OS X; version=10.14; arch=x86_64; networkInterfaces=System.Object[]; 
                  hostname=Holly-Flax-Mac.local; displayName=Holly-Flax-Mac.local; systemTimezone=-600; 
                  templateName=macosx-darwin-x86_64; remoteIP=80.87.24.84; active=False; sshdParams=System.Object[]; 
                  allowSshPasswordAuthentication=False; allowSshRootLogin=False; 
                  allowMultiFactorAuthentication=False; allowPublicKeyAuthentication=False; modifySSHDConfig=False; 
                  agentVersion=0.10.53; connectionHistory=System.Object[]; sshRootEnabled=True; 
                  id=5c9b95f84cbd1376318c5148; _id=5c9b95f84cbd1376318c5148; serialNumber=VMqYxmXmp3io; ById=_id; 
                  ByName=displayName; TypeName=; TypeNameSingular=system; TypeNamePlural=systems; 
                  Targets=System.Object[]; TargetSingular=System.Object[]; TargetPlural=System.Object[]}
targetId        : 5c8a81131f24752158a420a4
targetType      : system_group
targetInfo      : @{attributes=; id=5c8a81131f24752158a420a4; name=All Systems; type=system_group; ById=id; 
                  ByName=name; TypeName=; TypeNameSingular=system_group; TypeNamePlural=systemgroups; 
                  Targets=System.Object[]; TargetSingular=System.Object[]; TargetPlural=System.Object[]}
paths           : {System.Object[]}