Using the vRSLCM API to Create the Global Environment with VMware Identity Manager (Standard Deployment)

vRSLCM API VIDM

Published on 23 August 2022 by Christopher Lewis. Words: 2060. Reading Time: 10 mins.

In this post, we will look at how we can use the VMware vRealize Suite Lifecycle Manager (vRSLCM) API to configure the Global Environment and install a single VMware Identity Manager (VIDM) Appliance. The Global Environment is required to install vRealize Automation and also provides a Single Sign-On (SSO) Solution for the vRealize Suite.

We are going to be using cURL to complete API calls to complete the following operational tasks:

Create a Self-Signed SSL Certificate for the VIDM cluster.
Download the VIDM Product Binaries from MyVMware (aka VMware Customer Connect)
Create the Global Environment and deploy VIDM 3.3.5 (Standard Deployment)

This post is a part of a series that covers how we can install, configure and manage the vRealize Suite using the vRSLCM API.

Prerequisites

The following prerequisites are required for this blog post:

vRSLCM 8.6.x (or above) has been deployed successfully within the environment.
vRSLCM local administrator (admin@local) credentials.
All forward and reverse DNS entries for the VIDM appliance have be configured.

Walkthrough

Create a Self-Signed SSL Certificate for VIDM

Overview

In this section we are going to use the vRSLCM API to create a self-signed certificate for a single node deployment of VIDM.

API Request

The following REST API request is required:

Request Type: POST
Request URL: https://{vrslcm.fqdn}/lcm/locker/api/v2/certificates
Request Header(s):
- Accept: application/json
- Content-Type: application/json
- Authorization: Basic {insert credential hash}
Request Body Values:
- alias - the user friendly name for the certificate in the UI.
- cN - the fqdn of the product, such as idm.thecloudxpert.local.
- ip - (OPTIONAL) a list of IP addresses that should be included in the certificate.
- host - a list of the fqdns of each host that should be included in the certificate.
- oU - the Organizational Unit value for the SSL certitifcate.
- size - the Key Length of the certificate, either 2048 or 4096.
- o - the Organization value for the SSL certitifcate.
- l - the Location value for the SSL certificate.
- sT - the State value for the SSL certificate.
- c - the Country Code value for the SSL certificate.

Note:
It is a strong recommendation not to include IP addresses in SSL Certificates unless strictly necessary because it removes the flexibility of easily changing IP addresses of appliances.

API Example

An example cURL command for this REST API is:

curl --location --request POST 'https://{vrslcm.fqdn}/lcm/locker/api/v2/certificates' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {admin@local credential hash}' \
--data-raw '{
    "alias": "VMware Identity Manager",
    "cN": "idm.thecloudxpert.local",
    "ip": [],
    "host": [
        "idm.thecloudxpert.local"
        ],
    "oU": "thecloudxpert",
    "size": "2048",
    "o": "thecloudxpert",
    "l": "London",
    "sT": "United Kingdom",
    "c": "GB"
  }'

Note:
The –insecure flag is also required in the cURL command if you are using self-signed SSL certificates.

API Response

The response returned from a successful request (Status Code=200 OK) will be something like:

{
    "alias": "VMware Identity Manager",
    "key": "{privateKey}",
    "certChain": "{chainCert}",
    "leafCert": "{leafCert}",
    "validations": [],
    "validity": {
        "period": "1 year, 11 months and 28 days",
        "expiresOn": "2024-08-22T11:40:48.000+0000",
        "issuedOn": "2022-08-23T11:40:48.000+0000",
        "healthy": true
    },
    "certInfo": {
        "subject": "CN=idm.thecloudxpert.local,OU=thecloudxpert,O=thecloudxpert,L=London,ST=United Kingdom,C=GB",
        "issuer": "CN=vRealize Suite Lifecycle Manager Locker CA,O=VMware,C=IN",
        "san": "DNS: idm.thecloudxpert.local",
        "algorithm": "SHA256WITHRSA",
        "keyAlgorithm": "RSA",
        "keyLength": 2048,
        "sha256": "{sha256 fingerprint}",
        "sha1": "{sha1 fingerprint}"
    }
}

For more information on managing certificates in vRSLCM, see Using the vRealize Suite Lifecycle Manager (vRSLCM) API for vRSLCM Day 2 Operations - Managing SSL certificates .

Download the VIDM Product Binaries from MyVMware (aka VMware Customer Connect)

Overview

We are now going to use a vRSLCM API request to download the VIDM 3.3.5 product installation binaries (OVA) from My VMware (aka Customer Connect) and store them on the vRSLCM appliance.

POST API Request

The following REST API request is required:

Request Type: POST
Request URL: https://{vrslcm.fqdn}/lcm/lcops/api/v2/settings/my-vmware/product-binaries/download
Request Header(s):
- Accept: application/json
- Content-Type: application/json
- Authorization: Basic {insert credential hash}
Request Body Values:
- productId - The ID (or shortcode) for the specific product which can be obtained through the section Get All Available Product Binaries from My VMware .
- producName - The Name for the specific product which can be obtained through the section Get All Available Product Binaries from My VMware .
- productVersion - The supported Version of the product which can be obtained through the section Get All Supported Versions of a Product above.
- productBinaryType - The Binary Type, either Install or Upgrade.
- productBinaryPath - This should be set to null when downloading from My VMware.
- componentName - This should be set to null when downloading from My VMware.
- mappingType - This should be set to null when downloading from My VMware.
- requestId - This should be set to null as it is generated as part of the API request.
- removeBinary - This should be set to null when downloading from My VMware.

API Example

An example cURL command for this REST API is:

curl --location --request POST 'https://{vrslcm.fqdn}/lcm/lcops/api/v2/settings/my-vmware/product-binaries/download' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {admin@local credential hash}' \
--data-raw '[
    {
    "productId": "vidm",
    "productVersion": "3.3.5",
    "productBinaryType": "Install",
    "productBinaryPath": null,
    "componentName": null,
    "mappingType": null,
    "productName": "VMware Identity Manager",
    "requestId": null,
    "removeBinary": null
    }
]'

Note:
The –insecure flag is also required in the cURL command if you are using self-signed SSL certificates.

API Response

When submitting that request, a request is created and the API response should be a request ID for you to track. Something similar to:

{
    "requestId": "68ad91d7-8df5-4316-8a05-46d0875437db"
}

Remeber we can track the progress of requests via the API too! Check out Using the vRealize Suite Lifecycle Manager (vRSLCM) API to track vRSLCM Requests for more information!

For more information on managing product binaries using the vRSLCM API, see Using the vRealize Suite Lifecycle Manager (vRSLCM) API for vRSLCM Day 2 Operations - Downloading Products from My VMware .

Create the Global Environment and deploy VIDM 3.3.5 (Standard Deployment)

Overview

We are going use this API call to create the Global Environment (aka globalenvironment) and deploy a single VMware Identity Manager appliance. As we can see there is a lot of information required within the REST API body. This is because we are, essentially, creating an answer file for the deployment wizard we would be stepping through if we did this via the UI.

API Request

The following REST API request is required:

Request Type: POST
Request URL: https://{vrslcm.fqdn}/lcm/lcops/api/v2/environments
Request Header(s):
- Accept: application/json
- Content-Type: application/json
- Authorization: Basic {admin@local credential hash}
Request Body Values:
- Infrastructure:
  - Properties:
    - dataCenterVmid - the target datacenter vmid in vRSLCM, see Using the vRealize Suite Lifecycle Manager (vRSLCM) API for vRSLCM Day 2 Operations - Managing Datacenters
    - vCenterName - the user friendly name of the vCenter Server.
    - vCenterHost - the FQDN of the vcenter server.
    - vcUsername - the vCenter username that has been assigned a role with sufficient priviliges in vCenter Server.
    - vcPassword - the password for the vCenter username. This can be specified as a credential stored in vRSLCM locker (using the format locker:password:{vmid}:{alias}) OR as a plain text password).
    - acceptEULA - a boolean value to accept the EULA.
    - enableTelemetry - a boolean value to accept / deny the Customer Experience Improvement Program (CEIP).
    - defaultPassword - the default password for the deployment. This can be specified as a credential stored in vRSLCM locker (using the format locker:password:{vmid}:{alias}) OR as a plain text password).
    - certificate - the default password for the deployment. This can be specified as a certificatestored in vRSLCM locker (using the format locker:certificate:{vmid}:{alias}).
    - cluster - the datacenter & cluster where the VMware Identity Manager will be installed (using the format {datacenter}#{cluster}).
    - storage - the name of the target datastore.
    - diskMode - The decision on wether to provision using thick or thin disks.
    - network - The name of the virtual switch port group for the network interface.
    - dns - A comma delimited list of DNS server IP Addresses.
    - domain - The DNS Domain for the virtual machine.
    - gateway - The IPv4 Gateway address for the vIDM network interface.
    - netmask The IPv4 Subnet Mask (such as 255.255.255.0).
    - searchpath - A comma separated list of the DNS Search domains.
    - timeSyncMode - This is either host or ntp. If we choose ntp then we also need to provide the FQDN or IPv4 address of the NTP servers in the ntp key/value pair.
- Products:
  - id - The short code for the vRealize Suite product being installed. In this instance we are using vidm.
  - version - The version of the vRealize Suite product being installed. In this instance we are using 3.3.5 but it could be anything upto the latest version depending on what is supported in the vRSLCM we are running.
  - Properties:
    - defaultConfigAdminEmail - The default email address for the configuration user in VIDM.
    - vidmAdminPassword - The default password for VIDM. This can be specified as a credential stored in vRSLCM locker (using the format locker:password:{vmid}:{alias}) OR as a plain text password).
    - syncGroupMembers - A boolean value to decide whether to synchronise AD Group Members automatically.
    - nodeSize - The size of the VIDM node(s) to be deployed. This is a value of xsmall, small, medium, large, xlarge or xxlarge. A value of large is recommended for vRealize Automation deployments.
    - defaultConfigurationUsername - The default config admin username for VIDM.
    - defaultConfigurationPassword - The default password for VIDM. This can be specified as a credential stored in vRSLCM locker (using the format locker:password:{vmid}:{alias}) OR as a plain text password).
    - certificate - The default password for the deployment. This can be specified as a certificate stored in vRSLCM locker (using the format locker:certificate:{vmid}:{alias}).
    - fipsEnabled - A boolean value on whether Federal Information Processing Standard (FIPS) should be enabled. Once enabled this cannot be disabled.
  - ClusterVIP:
    - Not Required for a standard deployment.
  - Nodes:
    - type - In a standard deployment this is always vidm-primary.
    - Properties:
      - vmName - The friendly name for the VIDM appliance in vCenter Server.
      - hostName - The fqdn of the VIDM appliance.
      - ip - The IPv4 address of the VIDM appliance.

API Example

An example cURL command for this REST API is:

curl --location --request POST 'https://{vrslcm.fqdn}/lcm/lcops/api/v2/environments' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {admin@local credential hash}'
--data-raw '{
  "environmentId": "globalenvironment",
  "environmentName": "globalenvironment",
  "infrastructure": {
    "properties": {
      "dataCenterVmid": "{dataCenterVmid}",
      "regionName": "",
      "zoneName": "",
      "vCenterName": "{vcName}",
      "vCenterHost": "{vcFqdn}",
      "vcUsername": "{vcUsername}",
      "vcPassword": "locker:password:{vmid}:{alias}",
      "acceptEULA": "true",
      "enableTelemetry": "false",
      "defaultPassword": "locker:password:{vmid}:{alias}",
      "certificate": "{certReference}",
      "cluster": "{datacenter}#{cluster}",
      "storage": "{datastore}",
      "folderName": "",
      "resourcePool": "",
      "diskMode": "thin",
      "network": "{portGroup}",
      "masterVidmEnabled": "false",
      "dns": "{dnsServer1},{dnsServer2}",
      "domain": "thecloudxpert.local",
      "gateway": "{ipv4Gateway}",
      "netmask": "{ipv4SubnetMask}",
      "searchpath": "thecloudxpert.local",
      "timeSyncMode": "host",
      "ntp": "",
      "isDhcp": "false"
    }
  },
  "products": [
    {
      "id": "vidm",
      "version": "3.3.5",
      "properties": {
        "defaultConfigurationEmail": "configadmin@thecloudxpert.local",
        "vidmAdminPassword": "locker:password:{vmid}:{alias}",
        "syncGroupMembers": true,
        "nodeSize": "xsmall",
        "defaultConfigurationUsername": "configadmin",
        "defaultConfigurationPassword": "locker:password:{vmid}:{alias}",
        "defaultTenantAlias": "",
        "vidmDomainName": "",
        "certificate": "{certificate}",
        "contentLibraryItemId": "",
        "fipsMode": "false"
      },
      "clusterVIP": {
        "clusterVips": []
      },
      "nodes": [
        {
          "type": "vidm-primary",
          "properties": {
            "vmName": "idm",
            "hostName": "idm.thecloudxpert.local",
            "ip": "{vmIpv4Address}"
          }
        }
      ]
    }
  ]
}'

Note:
Remember, the –insecure flag is also required in the cURL command if you are using self-signed SSL certificates.

API Response

When submitting a successful request (Status Code = 200 OK), you should receive a response that shows the request id:

{
    "requestId": "globalenvironment"
}

We can track the progress of vRSLCM requests via the API. Check out Using the vRealize Suite Lifecycle Manager (vRSLCM) API to track vRSLCM Requests for more information.

Once the state of the vRSLCM request is COMPLETED we can then continue on to complete the upgrade.

Wrapping It All Up!

In this post we used the vRSLCM API to create a globalenvironment within a new deployment of vRSLCM. It is important to understand that you can only ever have one globalenvironment within a single vRSLCM instance. Therefore, if this environment already exists (for example, it has been created by the installation of vRealize Automation using the Easy Installer), then you cannot create another globalenvironment in the same vRSLCM instance. Furthermore, this means you can also only have one VIDM install per vRSLCM deployment too.

Now that we have VIDM installed we can install other vRealize Suite products into a new vRSLCM environment that can make use of VIDM as a single sign-on source.

You can expand a single node VIDM deployment to a cluster deployment as well, but the general recommendation is to deploy a cluster deployment upfront if that is what you are going to need long term. We will cover the cluster deployment in a very similar post called, Using the vRSLCM API to Create the Global Environment and Deploy VMware Identity Manager (Cluster Deployment)

If this API this snippet has been helpful, make sure you checkout the rest of the series !

Published on 23 August 2022 by Christopher Lewis. Words: 2060. Reading Time: 10 mins.

Blog Categories: VMware vRealize Suite Lifecycle Manager VMware Identity Manager