HPE GreenLake SCIM User and Group Management developer guide

This section covers authentication, permissions, and practical examples for implementing user and group management using the SCIM API.

Endpoints

Endpoints are the host URLs to which you will submit your API requests. To access HPE GreenLake SCIM User and Group Management APIs, use the unified API:

https://global.api.greenlake.hpe.com

URIs

/identity/v2beta1/scim/v2/Users
/identity/v2beta1/scim/v2/Users/{userId}
/identity/v2beta1/scim/v2/Groups
/identity/v2beta1/scim/v2/Groups/{groupId}
/identity/v2beta1/scim/v2/extensions/Groups/{groupId}/users
/identity/v2beta1/scim/v2/extensions/Users/{userId}/groups

Getting an access token

You must create a personal API client and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token. To do this:

Create a personal API client.
- Select the HPE GreenLake Cloud Platform service.
Generate an access token.
- View code samples for generating an access token.
Use the access token as an authorization bearer token to make secure REST API calls.

Access and permissions

Endpoint	Permission	Resource
`GET /identity/v2beta1/scim/v2/Users`	identity.users.read	User
`POST /identity/v2beta1/scim/v2/Users`	identity.users.create	User
`GET /identity/v2beta1/scim/v2/Users/{userId}`	identity.users.read	User
`PATCH /identity/v2beta1/scim/v2/Users/{userId}`	identity.users.update	User
`DELETE /identity/v2beta1/scim/v2/Users/{userId}`	identity.users.delete	User
`GET /identity/v2beta1/scim/v2/Groups`	identity.user-groups.read	Group
`POST /identity/v2beta1/scim/v2/Groups`	identity.user-groups.create	Group
`GET /identity/v2beta1/scim/v2/Groups/{groupId}`	identity.user-groups.read	Group
`PATCH /identity/v2beta1/scim/v2/Groups/{groupId}`	identity.user-groups.update	Group
`DELETE /identity/v2beta1/scim/v2/Groups/{groupId}`	identity.user-groups.delete	Group

:::info Learn more about configuring roles and permissions in the HPE GreenLake Cloud User Guide. :::

Rate limits

Group management:

Operation	Endpoint	Request limit
GET	`/identity/v2beta1/scim/v2/Groups`	6000 per minute
GET	`/identity/v2beta1/scim/v2/Groups/{groupId}`	6000 per minute
CREATE	`POST /identity/v2beta1/scim/v2/Groups`	1000 per minute
PATCH	`PATCH /identity/v2beta1/scim/v2/Groups/{groupId}`	1000 per minute
DELETE	`DELETE /identity/v2beta1/scim/v2/Groups/{groupId}`	1000 per minute

User management:

Operation	Endpoint	Request limit
GET	`/identity/v2beta1/scim/v2/Users`	6000 per minute
GET	`/identity/v2beta1/scim/v2/Users/{userId}`	6000 per minute
CREATE	`POST /identity/v2beta1/scim/v2/Users`	1000 per minute
DELETE	`DELETE /identity/v2beta1/scim/v2/Users/{userId}`	1000 per minute

Group extensions:

Operation	Endpoint	Request limit
GET	`/identity/v2beta1/scim/v2/extensions/Groups/{groupId}/users`	6000 per minute

User extensions:

Operation	Endpoint	Request limit
GET	`/identity/v2beta1/scim/v2/extensions/Users/{userId}/groups`	6000 per minute

Making it all work

This section provides examples of creating users and explains SCIM attributes, HPE GreenLake extensions, and POSIX user attributes.

Creating a new user with SCIM attributes

Use the POST /identity/v2beta1/scim/v2/Users endpoint create a new user account with required SCIM attributes and HPE GreenLake extensions.

To learn more about the SCIM attributes and extensions, see Understanding SCIM.

Example request body:

{
  "schemas": "urn:ietf:params:scim:schemas:core:2.0:User",
  "userName": "abc@xyz.com",
  "displayName": "Barbara Jensen",
  "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:User": {
    "countryCode": "US"
  },
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "primary": true,
      "value": "abc@xyz.com"
   }
  ]
}

Sample API response:

{
  "schemas": "urn:ietf:params:scim:schemas:core:2.0:User",
  "id": "00gs3w909WxZ4CIjl356",
  "active": false,
  "userName": "abc@xyz.com",
  "displayName": "Joe Smith",
  "meta": {
    "created": "string",
    "lastModified": "string",
    "lastLogin": "string",
    "location": "string",
    "resourceType": "User",
    "version": "string"
  },
  "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:User": {
    "status": "STAGED",
    "countryCode": "US",
    "primaryEmailVerified": true,
    "hpe_principal": "user:448ebfdb-7bc9-402f-9eb0-f9a86c06ca5a",
    "source": "Local",
    "sourceInstance": "organization UUID"
  },
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "primary": true,
      "value": "abc@xyz.com"
    }
  ]
}

Understanding SCIM

SCIM (System for Cross-domain Identity Management) schemas define the attributes and structure of resources like users and groups in identity management systems. These schemas provide a standardized way to represent identity data, enabling interoperability between different systems and services.

A SCIM schema consists of:

A unique identifier (URI)
A set of attribute definitions
Metadata about the resource type

SCIM schemas allow organizations to:

Consistently represent user identity data across systems.
Automate user provisioning and deprovisioning.
Enable secure identity synchronization between applications.
Support cloud-based identity management solutions.

For more information, see the SCIM 2.0 documentation.

HPE GreenLake implements extensions to the SCIM schemas.

HPE user extension attributes	HPE group extension attributes
`status` - User status (for example, "STAGED")	`hpe_principal` - Group principal identifier
`countryCode` - User's country code (for example, "US")	`groupDescription` - Description of the group
`primaryEmailVerified` - Email verification status	`source` - Source system (for example, "Local")
`hpe_principal` - User principal identifier	`sourceInstance` - The organization's UUID
`source` - Source system (e.g., "Local")
`sourceInstance` - Organization UUID

Example HPE SCIM schemas:

{
    "Resources": [
        {
            "schemas": "urn:ietf:params:scim:schemas:core:2.0:User",
            "id": "00gs3w909WxZ4CIjl356",
            "active": false,
            "userName": "abc@xyz.com",
            "displayName": "Joe Smith",
            "meta": {
                "created": "string",
                "lastModified": "string",
                "lastLogin": "string",
                "location": "string",
                "resourceType": "User",
                "version": "string"
            },
            "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:User": {
                "status": "STAGED",
                "countryCode": "US",
                "primaryEmailVerified": true,
                "hpe_principal": "user:448ebfdb-7bc9-402f-9eb0-f9a86c06ca5a",
                "source": "Local",
                "sourceInstance": "organization UUID"
            },
            "name": {
                "familyName": "Smith",
                "givenName": "Joe"
            },
            "emails": [
                {
                    "primary": true,
                    "value": "abc@xyz.com"
                }
            ]
        }
    ]
}

{
  "Resources": [
    {
      "schemas": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "id": "00gs3w909WxZ4CIjl356",
      "displayName": "Sales Group",
      "meta": {
        "created": "string",
        "lastModified": "string",
        "location": "string",
        "resourceType": "Group"
      },
      "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:Group": {
        "hpe_principal": "user-group:448ebfdb-7bc9-402f-9eb0-f9a86c06ca5a",
        "groupDescription": "Office users",
        "source": "Local",
        "sourceInstance": "organization UUID"
      }
    }
  ]
}

Creating a user with SCIM and POSIX attributes

Use the POST /identity/v2beta1/scim/v2/Users endpoint create a new user account with required SCIM attributes and POSIX-user attributes relevant to POSIX-compliant systems. To learn more, see Understanding POSIX.

Sample request body:

{
  "schemas": "urn:ietf:params:scim:schemas:core:2.0:User",
  "userName": "abc@xyz.com",
  "displayName": "Barbara Jensen",
  "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:User": {
    "countryCode": "US"
  },
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "primary": true,
      "value": "abc@xyz.com"
    }
  ]
}

Sample API response:

{
  "schemas": "urn:ietf:params:scim:schemas:core:2.0:User",
  "id": "00gs3w909WxZ4CIjl356",
  "active": false,
  "userName": "abc@xyz.com",
  "displayName": "Barbara Jensen",
  "meta": {
    "created": "string",
    "lastModified": "string",
    "lastLogin": "string",
    "location": "string",
    "resourceType": "User",
    "version": "string"
  },
  "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:User": {
    "status": "STAGED",
    "countryCode": "US",
    "primaryEmailVerified": true,
    "hpe_principal": "user:448ebfdb-7bc9-402f-9eb0-f9a86c06ca5a",
    "source": "Local",
    "sourceInstance": "organization UUID"
  },
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "primary": true,
      "value": "abc@xyz.com"
    }
  ],
  "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:posix:User": {
    "uid": 1001,
    "userName": "jdoe",
    "gid": 2001,
    "homeDirectory": "/home/jdoe",
    "shell": "/bin/bash"
  }
}

Understanding POSIX

POSIX (Portable Operating System Interface) is a family of standards specified by the IEEE to maintain compatibility between different operating systems. It defines the API, command line shells, and utility interfaces for software compatibility with variants of Unix and other operating systems.

The POSIX user extension provides essential attributes needed for user accounts on POSIX-compliant systems. This extension is used when:

Provisioning users to Linux/Unix servers or containers.
Integrating with file systems that require numeric user or group IDs.
Managing SSH access or shell accounts.
Synchronizing with LDAP directories that include POSIX attributes.

The POSIX extension contains:

uid—A numeric identifier for the user account (User ID).
userName—The login name for the user.
gid—The primary group identifier (Group ID) for the user.
homeDirectory—The user's home directory path, for example, /home/username.
shell—The user's default command shell, for example, /bin/bash.

An example of a POSIX user schema:

{
  "urn:ietf:params:scim:schemas:extensions:hpe-greenlake:2.0:posix:User": {
    "uid": 1001,
    "userName": "jdoe",
    "gid": 2001,
    "homeDirectory": "/home/jdoe",
    "shell": "/bin/bash"
  }
}

Understanding Strongly Claimed Domains

To enable the SCIM Integration features, it is necessary to configure a strongly claimed domain in the organization.

GreenLake provides a TXT record that the user puts into their DNS records which GreenLake can validate automatically.
Once validated, the organization has claimed the domain.

For more details see Claiming a domain