NerdGraph tutorial: Manage user groups and access grants

You can use New Relic’s NerdGraph API to view and manage user groups and access grants. For how to do this in the UI, see the user management UI docs.

Requirements

Some requirements for managing users and groups via NerdGraph:

Requires Pro or Enterprise edition (Standard edition organizations can't configure groups or access grants).
If you're using SCIM provisioning: for that authentication domain, you can't create groups or add users to groups, because your groups and users are managed via SCIM.
You must be a user on the New Relic One user model. Other permissions-related requirements:
- Required user type: core user or full platform user
- Required role: Organization manager or Authentication domain manager

Before you start

Before using NerdGraph to manage users:

Ensure you have a decent understanding of our user management concepts
If you haven't already, it can help to look in the Organization and access UI to improve your understanding of how groups and access grants work, and to understand any access grants that already exist.
Have a good plan for the groups and access grants you need to create. It may help to map this out in a spreadsheet beforehand.
Note that the NerdGraph explorer has built-in docs that define the fields used in these requests.

Suggested workflow for creating groups and access grants

You can use these queries and mutations in various ways and in various orders, but here's one common workflow for setting up groups and access grants:

Query your users' information and available roles: this can be a helpful first place to start to make sure you understand what users you have in New Relic and the available roles. If you're just starting out, you may not have added users yet, and you may have only our standard roles.
Optional: Create a new group: Not available if using SCIM provisioning. You can either use existing groups or create a new group. After creating a group, you must give it access to roles and accounts by creating an access grant. Note that a group, on its own, doesn't grant any access to users in that group: it's only via access grants that users get access to roles and accounts.
Create an access grant: this is what assigns groups access to roles and to accounts.

When you're done, if there are already users in the group you've created and that group has an access grant, they should have access within a few minutes (although for EU region New Relic accounts, this can take up to 20 minutes or so). If your users are not yet in that group (which would be true if you just created a new group), you can add users to that group.

Query existing roles

Here's an example of returning information about roles:

{
  actor {
    organization {
      authorizationManagement {
        authenticationDomains {
          authenticationDomains {
            groups {
              groups {
                roles {
                  roles {
                    accountId
                    displayName
                    id
                    name
                    organizationId
                    type
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Here's an example result:

{
  "data": {
    "actor": {
      "organization": {
        "authorizationManagement": {
          "authenticationDomains": {
            "authenticationDomains": [
              {
                "groups": {
                  "groups": [
                    {
                      "roles": {
                        "roles": [
                          {
                            "accountId": "account-id",
                            "displayName": "name",
                            "id": "id",
                            "name": "role-name",
                            "organizationId": null,
                            "type": "role-type"
                          },
                          {
                            "accountId":null,
                            "displayName": "name",
                            "id": "id",
                            "name": "role-name",
                            "organizationId": "organization-id",
                            "type": "role-type"
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}

Query users

Here's an example of querying information about your users:

{
  actor {
    organization {
      userManagement {
        authenticationDomains {
          authenticationDomains {
            groups {
              groups {
                users {
                  users {
                    id
                    email
                    name
                    timeZone
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Here's an example result:

{
  "data": {
    "actor": {
      "organization": {
        "userManagement": {
          "authenticationDomains": {
            "authenticationDomains": [
              {
                "groups": {
                  "groups": [
                    {
                      "users": {
                        "users": [
                          {
                            "email": "example@newrelic.com",
                            "id": "123456789",
                            "name": "Example Relic",
                            "timeZone": "Etc/UTC"
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}

Create a group

Here's an example of creating a group:

mutation {
  userManagementCreateGroup(createGroupOptions: {authenticationDomainId: "YOUR_AUTH_DOMAIN", displayName: "GROUP_DISPLAY_NAME"}) {
    group {
      displayName
      id
    }
  }
}

Successful response:

{
  "data": {
    "userManagementCreateGroup": {
      "group": {
        "displayName": "GROUP_DISPLAY_NAME"
      "id": "GROUP_ID"
      }
    }
  }
}

Update user group

Here's an example of updating a group.

mutation {
  userManagementUpdateGroup(updateGroupOptions: {displayName: "YOUR_UPDATED_GROUP_NAME", id: "GROUP_ID"}) {
    group {
      id
      displayName
    }
  }
}

Response for success:

{
  "data": {
    "userManagementUpdateGroup": {
      "group": {
        "displayName": "YOUR_UPDATED_GROUP_NAME",
        "id": "GROUP_ID"
      }
    }
  }
}

Response for failure:

{
  "data": {
    "userManagementUpdateGroup": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "Group could not be found",
      "path": [
        "userManagementUpdateGroup"
      ]
    }
  ]
}

Delete a group

Here's an example of deleting a group:

mutation {
  userManagementDeleteGroup(groupOptions: {id: "GROUP_ID"}) {
    group {
      id
    }
  }
}

Response for success:

{
  "data": {
    "userManagementDeleteGroup": {
      "group": {
        "id": "GROUP_ID"
      }
    }
  }
}

Response for failure:

{
  "data": {
    "userManagementDeleteGroup": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "Couldn't find Group with 'id'='ENTERED_GROUP_ID",
      "path": [
        "userManagementDeleteGroup"
      ]
    }
  ]
}

Add users to groups

Here's an example of adding users to groups:

mutation {
  userManagementAddUsersToGroups(addUsersToGroupsOptions: {groupIds: [GROUP_ID_1, GROUP_ID_2], userIds: [YOUR_USERS_IDS]}) {
    groups {
      displayName
      id
    }
  }
}

Response for success:

{
  "data": {
    "userManagementAddUsersToGroups": {
      "groups": [
        {
          "displayName": "GROUP_1_NAME",
          "id": "GROUP_ID_1"
        },
        {
          "displayName": "GROUP_NAME_2",
          "id": "GROUP_ID_2"
        }
      ]
    }
  }
}

Response for failure:

{
  "data": {
    "userManagementAddUsersToGroups": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "The following ids were not found: group_ids: 'NON_EXISTENT_GROUP_ID'",
      "path": [
        "userManagementAddUsersToGroups"
      ]
    }
  ]
}

Remove users from groups

Here's an example of removing users from groups:

mutation {
  userManagementRemoveUsersFromGroups(removeUsersFromGroupsOptions: {groupIds: [YOUR_GROUP_IDS], userIds: [YOUR_USER_IDS]}) {
    groups {
      displayName
      id
    }
  }
}

Response for success:

{
  "data": {
    "userManagementRemoveUsersFromGroups": {
      "groups": [
        {
          "displayName": "YOUR_GROUP_NAME",
          "id": "YOUR_GROUP_ID"
        }
      ]
    }
  }
}

Response for failure:

{
  "data": {
    "userManagementRemoveUsersFromGroups": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "The following ids were not found: user_ids: 'NON-EXISTENT_USER_ID'",
      "path": [
        "userManagementRemoveUsersFromGroups"
      ]
    }
  ]
}

Grant access to group

Here's an example of creating an access grant (access to a role and an account) for a group:

mutation {
  authorizationManagementGrantAccess(grantAccessOptions: {groupId: "YOUR_GROUP_ID", accountAccessGrants: {accountId: "ACCOUNT_ID", roleId: "ROLE_ID"}}) {
    roles {
      displayName
      accountId
    }
  }
}

Response for success:

{
  "data": {
    "authorizationManagementGrantAccess": {
      "roles": [
        {
          "displayName": "ROLE_NAME_1",
          "id": "ROLE_ID_1"
        },
        {
          "displayName": "ROLE_NAME_2",
          "id": "ROLE_ID_2"
        },
        {
          "displayName": "ROLE_NAME_3",
          "id": "ROLE_ID_3"
        },
        {
          "displayName": "ROLE_NAME_4",
          "id": "ROLE_ID_4"
        }
      ]
    }
  }
}

Response for failure:

{
  "data": {
    "authorizationManagementGrantAccess": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "Validation failed: Role must exist, Role can't be blank, Role scope does not match granted_on type",
      "path": [
        "authorizationManagementGrantAccess"
      ]
    }
  ]
}

Revoke grants from group

Here's an example of revoking access grants from groups:

mutation {
  authorizationManagementRevokeAccess(revokeAccessOptions: {accountAccessGrants: {accountId: "ACCOUNT_ID", roleId: "ROLE_ID"}, groupId: "GROUP_ID"}) {
    roles {
      accountId
      displayName
    }
  }
}

Response for success:

{
  "data": {
    "authorizationManagementRevokeAccess": {
      "roles": [
         {
          "displayName": "ROLE_NAME_1",
          "id": "ROLE_ID_1"
        },
        {
          "displayName": "ROLE_NAME_2",
          "id": "ROLE_ID_2"
        },
        {
          "displayName": "ROLE_NAME_3",
          "id": "ROLE_ID_3"
        }
      ]
    }
  }
}