Skip to main content

IAM operations

note

accessAdmin permission is required for all IAM operations.

Endpoint:

POST https://graphql.us.jupiterone.io/

Headers:

Content-Type: application/json
Accept: application/json
JupiterOne-Account: {Account_ID}
Authorization: Bearer {API_Key}

Get IAM groups​

Query: iamGroups

Retrieves all account groups within the query limit.

  • limit: (required) max number of records to return
  • cursor: (optional) continuation token
query Query($limit: Int!, $cursor: String) {
  iamGroups(limit: $limit, cursor: $cursor) {
    items {
      id
      name
      description
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

API Samples

Sample (S1): iamGroups

(S1): Request

{
  "limit": 5
}

(S1): Response

{
  "data": {
    "iamGroups": {
      "items": [
        {
          "id": "12c2d370-89ef-4280-970b-d520ca1837be",
          "name": "Users",
          "description": ""
        },
        {
          "id": "dd354c7a-1b9b-4579-ac5e-873fe3b2c851",
          "name": "Administrators",
          "description": "Admin users"
        }
      ],
      "pageInfo": {
        "endCursor": "eyJhY2NvdW50I...",
        "hasNextPage": true
      }
    }
  }
}

Get Users of IAM group​

Query: iamGroupUsers

Retrieves all group members of the specified group (by id) within the query limit.

  • groupId: (required) unique group identifier
  • limit: (required) max number of records to return
  • cursor: (optional) continuation token

    Note: The item.id property in the response is the JupiterOne uid.

query Query($groupId: String!, $limit: Int!, $cursor: String) {
  iamGroupUsers(groupId: $groupId, limit: $limit, cursor: $cursor) {
    items {
      id
      email
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

API Samples

Sample (S1): iamGroupUsers

(S1): Request

{
  "groupId": "22c2d370-89ef-4280-970b-d520ca1837be",
  "limit": 5
}

(S1): Response

{
  "data": {
    "iamGroupUsers": {
      "items": [
        {
          "id": "222xxx222_abc",
          "email": "abc@mycompany.com"
        },
        {
          "id": "222xxx222_def@mycompany.com",
          "email": "def@mycompany.com"
        }
      ],
      "pageInfo": {
        "endCursor": "eyJ1c2VyIjoiaj...",
        "hasNextPage": true
      }
    }
  }
}

Add IAM User to Group​

Mutation: addIamUserToGroupByEmail

Adds a user to a group using the specified email and group ID.

  • groupId: (required)
  • userEmail: (required)
mutation Mutation($groupId: String!, $userEmail: String!) {
  addIamUserToGroupByEmail(groupId: $groupId, userEmail: $userEmail) {
    success
  }
}

API Samples

Sample (S1): addIamUserToGroupByEmail

(S1): Request

{
  "groupId": "22c2d370-89ef-4280-970b-d520ca1837be",
  "userEmail": "abc@mycompany.com"
}

(S1): Response

{
  "data": {
    "addIamUserToGroupByEmail": {
      "success": true
    }
  }
}

Remove IAM user from group​

Mutation: removeIamUserFromGroupByEmail

Removes a user from a group using the specified email and group ID.

  • groupId: (required)
  • userEmail: (required)
mutation Mutation($groupId: String!, $userEmail: String!) {
  removeIamUserFromGroupByEmail(groupId: $groupId, userEmail: $userEmail) {
    success
  }
}

API Samples

Sample (S1): removeIamUserFromGroupByEmail

(S1): Request

{
  "groupId": "22c2d370-89ef-4280-970b-d520ca1837be",
  "userEmail": "xyz@mycompany.com"
}

(S1): Response

{
  "data": {
    "removeIamUserFromGroupByEmail": {
      "success": true
    }
  }
}

Create IAM Group​

Mutation: createIamGroup

Creates a new group with a specified name and optionally: description, queryPolicy, and/or abacPermissions.

  • name: (required) must be unique to all other groups.
  • description: (optional)
  • abacPermissions: (optional)
  • queryPolicy: (optional)
mutation Mutation(
  $name: String!
  $description: String
  $abacPermissions: [String!]
  $queryPolicy: [JSON!]
) {
  createIamGroup(
    name: $name
    description: $description
    abacPermissions: $abacPermissions
    queryPolicy: $queryPolicy
  ) {
    id
    name
    description
  }
}

API Type Definitions

queryPolicy

Description: Group Query Policies define query access for members of a particular group. Setting this property via the IAM API will overwrite any existing queryPolicy for the given group. If updating this property, always define the full queryPolicy to enforce.

Type: list of JSON objects with primitive values or an array or primitive values.

type queryPolicy = [JSON!];
type JSON = {
  [key: string]: string | number | boolean || (string | number | boolean)[];
}

queryPolicy

abacPermissions

ABAC permissions define application access for members of a perticular group. Setting this property via the IAM API will overwrite any existing permissions for the given group. If updating this property, always define the full list of permissions that should be granted.

Type: list of valid permission strings (see table below).

type abacPermissions = [permission!]
type permission = string // must be a valid permission string

Permission Strings: READ-ONLY

DISPLAY NAME (J1 APP)ACCESSPERMISSION
All Apps And ResourcesREADfullReadAccess
Shared: QuestionsREADreadQuestions
GraphDataREADreadGraph
Home PageREADaccessLanding
AssetsREADaccessAssets
PoliciesREADaccessPolicies
ComplianceREADaccessCompliance
AlertsREADaccessRules
GraphViewerREADaccessGalaxy
InsightsREADaccessInsights
IntegrationsREADaccessIntegrations
Endpoint ComplianceREADaccessEndpointCompliance

Permission Strings: ADMIN

DISPLAY NAME (J1 APP)ACCESSPERMISSION
All Apps And ResourcesADMINaccessAdmin
Shared: QuestionsADMINwriteQuestions
GraphDataADMINwriteGraph
Home PageADMINadminLanding
AssetsADMINadminAssets
PoliciesADMINadminPolicies
ComplianceADMINadminCompliance
AlertsADMINadminRules
GraphViewerADMINadminGalaxy
InsightsADMINadminInsights
IntegrationsADMINadminIntegrations
Endpoint ComplianceADMINadminEndpointCompliance
ENABLE API KEY ACCESS*apiKeyUser

API Samples

Sample (S1): createIamGroup

(S1): Request

{
  "name": "Users"
}

(S1): Response

{
  "data": {
    "createIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca1837be",
      "name": "Users"
    }
  }
}

Sample (S2): createIamGroup

(S2): Request

{
  "name": "UsersX",
  "description": "A group for X users"
}

(S2): Response

{
  "data": {
    "createIamGroup": {
      "id": "11c2d370-89ef-4280-970b-d520ca1837be",
      "name": "UsersX",
      "description": "A group for X users"
    }
  }
}

Sample (S3): createIamGroup

(S3): Request

{
  "name": "Support",
  "description": "A group for support users",
  "queryPolicy": [
    {
      "_type": ["aws_ecr_image", "bitbucket_pullrequest"]
    }
  ]
}

(S3): Response

{
  "data": {
    "createIamGroup": {
      "id": "23434-454-45656-65656-4564564565",
      "name": "Support",
      "description": "A group for support users"
    }
  }
}

Sample (S4): createIamGroup

(S4): Request

{
  "name": "Admins",
  "queryPolicy": [
    {
      "_type": "aws_ecs_task_definition",
      "_class": "Account"
    },
    {
      "_type": "aws_ecr_image"
    }
  ]
}

(S4): Response

{
  "data": {
    "createIamGroup": {
      "id": "87787-6787-678678-778-6786786",
      "name": "Admins"
    }
  }
}

Access All Actions and Resources

You can use an API token to access all actions and resources

Update IAM Group​

Mutation: updateIamGroup

Updates a group's properties: name, description, queryPolicy, and/or abacPermissions.

  • id: (required) must tie to an existing group.
  • name: (optional) must be unique to all other groups.
  • description: (optional)
  • abacPermissions: (optional)
  • queryPolicy: (optional)
mutation Mutation(
  $id: String!
  $name: String
  $description: String
  $abacPermissions: [String!]
  $queryPolicy: [JSON!]
) {
  updateIamGroup(
    id: $id
    name: $name
    description: $description
    abacPermissions: $abacPermissions
    queryPolicy: $queryPolicy
  ) {
    id
    name
    description
  }
}

API Type Definitions

queryPolicy

Description: Group Query Policies define query access for members of a particular group. Setting this property via the IAM API will overwrite any existing queryPolicy for the given group. If updating this property, always define the full queryPolicy to enforce.

Type: list of JSON objects with primitive values or an array or primitive values.

type queryPolicy = [JSON!];
type JSON = {
  [key: string]: string | number | boolean || (string | number | boolean)[];
}

abacPermissions

Description: ABAC permissions define application access for members of a perticular group. Setting this property via the IAM API will overwrite any existing permissions for the given group. If updating this property, always define the full list of permissions that should be granted.

Type: list of valid permission strings (see table below).

type abacPermissions = [permission!];
type permission = string; // must be a valid permission string

Permission Strings: READ-ONLY

DISPLAY NAME (J1 APP)ACCESSPERMISSION
All Apps And ResourcesREADfullReadAccess
Shared: QuestionsREADreadQuestions
GraphDataREADreadGraph
Home PageREADaccessLanding
AssetsREADaccessAssets
PoliciesREADaccessPolicies
ComplianceREADaccessCompliance
AlertsREADaccessRules
GraphViewerREADaccessGalaxy
InsightsREADaccessInsights
IntegrationsREADaccessIntegrations
Endpoint ComplianceREADaccessEndpointCompliance

Permission Strings: ADMIN

DISPLAY NAME (J1 APP)ACCESSPERMISSION
All Apps And ResourcesADMINaccessAdmin
Shared: QuestionsADMINwriteQuestions
GraphDataADMINwriteGraph
Home PageADMINadminLanding
AssetsADMINadminAssets
PoliciesADMINadminPolicies
ComplianceADMINadminCompliance
AlertsADMINadminRules
GraphViewerADMINadminGalaxy
InsightsADMINadminInsights
IntegrationsADMINadminIntegrations
Endpoint ComplianceADMINadminEndpointCompliance
ENABLED API KEY ACCESS*apiKeyUser

API Samples

Sample (S1): updateIamGroup

(S1): Request

{
  "id": "90909-11ef-4280-970b-4444ca1837be",
  "name": "Users"
}

(S1): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca1837be",
      "name": "Users",
      "description": "original description.."
    }
  }
}

Sample (S2): updateIamGroup

(S2): Request

{
  "id": "90909-11ef-4280-970b-4444ca",
  "name": "UsersX",
  "description": "A group for X users"
}

(S2): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca",
      "name": "UsersX",
      "description": "A group for X users"
    }
  }
}

Sample (S3): updateIamGroup

(S3): Request

{
  "id": "90909-11ef-4280-970b-4444ca",
  "abacPermissions": ["accessPolicies", "writeQuestions", "accessGalaxy"],
  "queryPolicy": [
    {
      "_type": "aws_ecs_task_definition"
    }
  ]
}

(S3): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca",
      "name": "UsersX",
      "description": "A group for X users"
    }
  }
}

Sample (S4): updateIamGroup

(S4): Request

{
  "id": "90909-11ef-4280-970b-4444ca",
  "description": "allow account class",
  "queryPolicy": [
    {
      "_type": "aws_ecs_task_definition",
      "_class": "Account"
    },
    {
      "_integrationType": ["whitehat"]
    }
  ]
}

(S4): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca",
      "name": "UsersX",
      "description": "allow account class"
    }
  }
}

Set RBAC Permissions​

Resource permissions are used to manage access to the following resources: integrations, dashboards, and rules. You can set resource permissions for a user group by using the following gql mutation:

Mutation: setResourcePermission

Creates/updates a resource permission for a group

  • subjectType: (required) Currently only supports group for user group
  • subjectId: (required) The id of the user group
  • resourceArea: (required) dashboard, integration, or rule
  • resourceType: (required) *, resource_group, dashboard, integration, or rule
  • resourceId: (required) The id of the resource or *
  • canCreate: (required)
  • canRead: (required) Must be true if canCreate, canUpdate or canDelete are true
  • canUpdate: (required)
  • canDelete: (required)
mutation SetResourcePermission(
  $subjectType: String!
  $subjectId: String!
  $resourceArea: String!
  $resourceType: String!
  $resourceId: String!
  canCreate: Boolean!
  canRead: Boolean!
  canUpdate: Boolean!
  canDelete: Boolean!
) {
  setResourcePermission(
    input: {
      subjectType: $subjectType
      subjectId: $subjectId
      resourceArea: $resourceArea
      resourceType: $resourceType
      resourceId: $resourceId
      canCreate: $canCreate
      canRead: $canRead
      canUpdate: $canUpdate
      canDelete: $canDelete
    }
  ) {
    subjectType
    subjectId
    resourceArea
    resourceType
    resourceId
    canCreate
    canRead
    canUpdate
    canDelete
  }
}

Contents