HPE GreenLake for Identity & Access Management developer guide

The examples in this guide help you use the Identity & Access Management APIs.

Prerequisites

Endpoints

Endpoints are the host URLs to which you will submit your API requests. To access Identity & Access Management APIs, use the unified API:

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

URIs

Unique Resource Identifiers (URIs) are used to identify a server or resource used within the users and workspaces. A URI is a full API path ending in an identification number. For example:

• /identity/v1/users/{userId}

Generating tokens

You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.

To access the HPE GreenLake platform Identity & Access Management API, proceed as follows:

1. Connect to the HPE GreenLake edge-to-cloud platform UI workspace.
2. Go to Manage Workspace > API > Create Credentials .
3. Select HPE GreenLake Platform from the Select Service Manager drop-down. If you do not see HPE GreenLake Platform as an option when configuring API client credentials, see the Getting Started Guide for more information.
4. Enter the Credential Name .
5. Click Create Credential .

Making It All Work

Identity management

The identity management APIs allow you to:

• Find information on existing users.
• Invite a user to a workspace.
• Find information on a single-user.
• Delete a user from a workspace.
• Update user preferences.

Obtain information on users in a workspace

To retrieve a list of users and their related information in the workspace, use the following request GET request:

GET https://global.api.greenlake.hpe.com/identity/v1/users

The information returned for each user is the following:

• User ID, username, status, and login status
• Pagination information: offset, count, items, and total

Sample response:

{
"offset": 0,
    "count": 2,
    "total": 2,
    "items": [
        {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "type": "string",
            "generation": 0,
            "createdAt": "2019-08-24T14:15:22Z",
            "updatedAt": "2019-08-24T14:15:22Z",
            "username": "user@example.com",
            "userStatus": "UNVERIFIED",
            "lastLogin": "2019-08-24T14:15:22Z"
        },
        {
            "id": "523a65de-2266-5012-bfeb-53cdddd16f08",
            "type": "string",
            "generation": 0,
            "createdAt": "2020-08-24T14:15:22Z",
            "updatedAt": "2021-08-24T14:15:22Z",
            "username": "user2@example.com",
            "userStatus": "VERIFIED",
            "lastLogin": "2019-08-24T14:15:22Z"
        }
    ]
}

Obtain information on a single user

To retrieve information on a specific user, make the following request GET request specifying the user ID:

GET https://global.api.greenlake.hpe.com/identity/v1/users/<id>

Inviting a user to the workspace

To invite a user to the same workspace where you created the access token, submit a POST request:

POST https://global.api.greenlake.hpe.com/identity/v1/users

Payload:

{
  "email": "string",
  "sendWelcomeEmail": true
}

In the request body, specify the user's email address and whether to send a welcome or not.

A valid response generates a location header, and the response payload returns a user invited message.

Disassociating a user from the workspace

To delete a user from a workspace, submit the following request specifying the path of the user ID.

DELETE https://global.api.greenlake.hpe.com/identity/v1/users/<id>

Updating your user preferences

To change your user preferences, use the following PUT request:

PUT https://global.api.greenlake.hpe.com/identity/v1/users/<id>

Payload:

{
    "language": "en",
    "idleTimeout": 1800
}

Credential Management

With the credential management APIs, you can:

• Create a credential
• List the credentials you have created
• Reset the secret of a credential
• Delete a credential

You can perform these operations for the HPE GreenLake platform service manager and provisioned service managers in standard enterprise, managed service provider (MSP), and MSP tenant workspaces.

The following API descriptions clarify the optional parameters for managing MSP tenant workspaces and provisioned service managers.

Create a credential

To create a new credential in a workspace, submit a POST request:

POST https://global.api.greenlake.hpe.com/workspaces/v1/credentials

The elements of the APIs payload are the credentialName and optionally associatedTenant and associatedServiceManagerProvision.

• Credential name — Human readable alias for this credential.
• Associated tenant (MSP only) — A reference to the tenant in which this credential will be created. If you supply an associatedTenant , it will be returned in the response payload.

You need to supply the UUID of the workspace. To find the UUID:

• Use the Get basic workspace information API to find your workspace UUID.
  • Alternatively, use the the HPE GreenLake platform UI .
• (MSP only) Use the Obtain a list of tenants API to find workspace UUIDs for the MSP tenant workspace.

"associatedTenant": {
    "resourceUri": "/workspaces/v1/workspaces/<UUID of Workspace>"
}

(Optional) Provide an associated service manager provision. This refers to the instance of the provisioned service in your workspace to which you want to link the credential. If you supply an associatedServiceManagerProvision, the response payload will return it.

You need to supply the UUID of the provisioned service instance.

• To find this UUID, use the GET a list of provisioned service managers API.

"associatedServiceManagerProvision": {
    "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/<UUID of provisioned service instance>"
}

Sample request with both associatedTenant and associatedServiceManagerProvision

{
    "credentialName": "<A human readable alias for your new credential>",
    "associatedServiceManagerProvision": {
        "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/767c0c92-5ecc-4952-85d6-04a2acaaf050"
    }
    "associatedTenant": {
        "resourceUri": "/workspaces/v1/workspaces/eba3541b-db86-465f-9cae-31f33ccb1fa0"
    }
}

Sample response

{
    "id": "fa4e341b-db86-495f-9cee-31f48bba1ea0",
    "credentialName": "My credential",
    "clientId": "fa4e341b-db86-495f-9cee-31f48bba1ea0",
    "clientSecret": "9163c936b93911ee822c16e5bfc542a7",
    "type": "credentials",
    "generation": 1,
    "createdAt": "2024-01-22 15:18:59.936526",
    "updatedAt": "2024-01-22 15:18:59.936526",
    "associatedTenant": {
        "resourceUri": "/workspaces/v1/workspaces/aa4e3a1a-cc83-335b-9cae-b93911ee822c",
        "tenantName": "Tenant ABC"
    },
    "associatedServiceManagerProvision": {
        "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/767c0c92-5ecc-4952-85d6-04a2acaaf050"
    }
}

Listing your credentials

To list the credentials, submit a GET request:

GET https://global.api.greenlake.hpe.com/workspaces/v1/credentials

• Associated service manager provision — If a credential was created with an associatedServiceManagerProvision it will be present in the response for that credential.
• Associated tenant (MSP only) — If a credential was created with an associatedTenant it will be present in the response for that credential.
• Filtering (MSP only) — For MSP workspaces, this GET endpoint supports filtering using the OData standard. To retrieve credentials in an MSP tenant, append ?filter='tenantId eq <The tenantId of interest>' to the GET request.

Sample response with associatedTenant and associatedServiceManagerProvision:

{
    "items": [
        {
            "credentialName": "Credential Demo",
            "associatedServiceManagerProvision": {
                "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/767c0c92-5ecc-4952-85d6-04a2acaaf050"
            },
            "associatedTenant": {
                "resourceUri": "/workspaces/v1/workspaces/aa4e3a1a-cc83-335b-9cae-b93911ee822c",
                "tenantName": "Tenant ABC"
            },
            "id": "b660bcc4-1914-45b1-81a8-fcff6cb82a9e",
            "clientId": "b660bcc4-1914-45b1-81a8-fcff6cb82a9e",
            "type": "credentials",
            "generation": 1,
            "createdAt": "2024-01-22 10:00:00.000000",
            "updatedAt": "2024-01-22 10:00:00.000000"
        }
    ],
    "count": 1
}

Reset the secret of a credential

Use the reset endpoint to regenerate the clientSecret of a credential. POST to the endpoint, supplying the id of the credential you wish to reset.

POST https://global.api.greenlake.hpe.com/workspaces/v1/credentials/{id}/reset

• Associated service manager provision — If a credential was created with an associatedServiceManagerProvision it will be present in the response for that credential.
• Associated tenant (MSP only) — If a credential was created with an associatedTenant it will be present in the response for that credential.

Sample response with associatedTenant and associatedServiceManagerProvision:

{
    "credentialName": "Credential Demo",
    "id": "fa4e341b-db86-495f-9cee-31f48bba1ea0",
    "clientId": "fa4e341b-db86-495f-9cee-31f48bba1ea0",
    "clientSecret": "8274d83827b93912dd811c16f5bfa542b6",
    "type": "credentials",
    "generation": 1,
    "createdAt": "2024-01-22 15:19:00.000000",
    "updatedAt": "2024-01-22 15:19:00.000000",
    "associatedServiceManagerProvision": {
        "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/767c0c92-5ecc-4952-85d6-04a2acaaf050"
    },
    "associatedTenant": {
        "resourceUri": "/workspaces/v1/workspaces/aa4e3a1a-cc83-335b-9cae-b93911ee822c",
        "tenantName": "Tenant ABC"
    },
}

Delete a credential

Use the delete endpoint to delete a credential. Submit a DELETE to the endpoint supplying the id of the credential you wish to delete.

DELETE https://global.api.greenlake.hpe.com/workspaces/v1/credentials/{id}

A successful deletion returns an HTTP status 204.

Filtering

Filters provide the ability to limit the resources that take part in the action of a REST call. When a REST call includes a filter, the GET or PUT action is restricted to a response that meets the filter requirements. Specify filters using the query parameter filter.

Filtering example

In this example of filtering, the query's resources are limited to results for the specified username. Within the filter, the separator is a space.

GET <URI>?filter=username eq 'user@example.com'

Filtering on a single property

filter = <propertyName> <comparison operation> <literal>

GET /identity/v1/users?filter=username eq 'user@example.com'

Property is the name of an attribute in the requested resource type, for example, username. The property name is always to the left of the operation. Specify nested property names with the / separator.

Examples of the possible filter values:

Operation evaluated. Operations compare properties against literals, for example, eq. All parameters except in require the property on the left and the literal on the right. The in parameter allows the property on either side.

Examples of operations:

Special case operations:

A Function can be used to extract information. A function is a block of reusable code that performs a single action. You pass a value into the function, which returns a value. These functions can be used in a filter:

A literal, for example, true, is what an operation compares a property to. For a successful matching operation, the data types must match, and the syntax determines the data type of the literals. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.

The following are examples of literals.

• String : Anything in 'single quotes'. Reserved characters in string literals must be URL encoded.
• Integer : -100, -1, 0, 1, 100
• Decimal : -3.14, -2.71, 2.71, 3.14
• Timestamp : 2019-10-12T07:20:50.52934852Z. The timestamp format is [RFC3339]
• Boolean : true, false
• Null : null. Null is equal to itself and nothing else. Null is not greater or less than anything.

Filtering on multiple properties

Logical operations facilitate filtering using multiple queries. Combine multiple operations using the operator and, for example:

Require both (and): createdAt eq '2020-09-21T14:19:09.769747' and workspaceName eq 'test'

OData filtering reference

This filtering is a subset of OData 4.0 filtering.