How To Use The Associations Functions
- What is a JumpCloud object?
- What Are Associations?
- Using Get-JCAssociation
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.
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 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.
Bryan Alders, Am Anemali, and Adam Ant are all directly associated with the user group "New User Group".
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.
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.
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.
| 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 |
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 |
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.
Get-JCAssociation -Type:user_group -Name:employeeThis 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.flaxThis 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-MacThis example will return all the associations for the system with displayName "Hollys-Mac"
- The field
displayNameis not enforced as a unique field for systems in JumpCloud. A warning will appear if a specified-namevalue returns more then one record.
Get-JCAssociation -Type:system -displayName:admins-mac.local
WARNING: Found "4" "system" with the "name" of "admins-mac.local"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:5c9o95o84lbe1376318an1s8This example will return all the associations for the system with an id value of "5c9o95o84lbe1376318an1s8"
Get-JCAssociation -Type:user -Id:5c9o95o84lbo1376318ot1s8This example will return all the associations for the user with an id value of "5c9o95o84lbo1376318ot1s8"
The -Direct switch parameter can be used with the Get-JCAssociations command to only output direct associations.
The -Indirect switch parameter can be used with the Get-JCAssociations command to only output indirect associations.
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"
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
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[]}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=holly.flax@sajumpcloud.com; 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=sa.admin@sajumpcloud.com; 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[]}