Skip to main content
Hitachi Vantara Knowledge

Access and authentication

With the HCP management API, resources are represented by URLs. Each request you make must specify one such URL. Each request must also include the credentials for the account you’re using to access HCP through the management API.

This section of the Help describes resource URLs and explains how to include account credentials in a management API request.

URL for HCP access through the management API

Using an IP address in URL

Normally, you let HCP choose the node on which to process a management API request. You can, however, use an IP address in the URL to access the system on a specific node. To do this, you replace the fully qualified domain name (FQDN) in the URL with the IP address for the node you want.

If the node has both an IPv4 address and an IPv6 address, you can use either address. For example, to access the namespaces resource on a node that has both the IPv4 address 192.168.210.16 and the IPv6 address 2001:0db8::101, you can use either of these URLs:

https://192.168.210.16:9090/mapi/tenants/finance/namespaces
https://[2001:0db8::101]:9090/mapi/tenants/finance/namespaces

Additionally, you need to provide the fully qualified domain name of the tenant in an HTTP Host header. With cURL, you do this with the -H option. For example:

-H "Host: finance.hcp.example.com"

In Python with PycURL, you do this with the HTTPHEADER option. For example:

curl.setopt(pycurl.HTTPHEADER, ["Host: finance.hcp.example.com"])
NoteIf you don’t know the IP addresses for the nodes in the HCP system, contact your HCP system administrator.

Using a hosts file

Typically, HCP is included as a subdomain in your DNS. If this is not the case, for access to the system, you need to use the tenant domain name in the URL and use a hosts file to define mappings of one or more node IP addresses to that domain name.

The location of the hosts file depends on the client operating system:

  • On Windows, by default: c:\windows\system32\drivers\etc\hosts
  • On Unix: /etc/hosts
  • On Mac OS® X: /private/etc/hosts
NoteIf HCP is not included in your DNS, the tenant domain name is a dummy domain name that follows the conventions for well-formed DNS names.
Hostname mappings

Each entry in a hosts file is a mapping of an IP address to a hostname. For an HCP tenant, the hostname must be the fully qualified domain name (FQDN) for the tenant.

Each hosts file entry you create for access to a tenant must include:

  • An IP address of a node in the HCP system
  • The FQDN of the tenant domain

For example, if the tenant domain name is finance.hcp.example.com and one of the HCP nodes has the IPv4 address 192.168.210.16 and the IPv6 address 2001:0db8::101, you could add either or both of these lines to the hosts file on the client:

192.168.210.16   finance.hcp.example.com
2001:0db8::101   finance.hcp.example.com

You can include comments in a hosts file either on separate lines or following a mapping on the same line. Each comment must start with a number sign (#). Blank lines are ignored.

Hostname mapping considerations

In the hosts file, you can map IP addresses for any number of nodes to a single domain name. The way a client uses multiple IP address mappings for a single domain name depends on the client platform. For information about how your client handles hosts file entries that define multiple IP address mappings for a single domain name, see your client documentation.

If any of the HCP nodes listed in the hosts file are unavailable, timeouts may occur when you use a hosts file to access the system through the management API.

Sample hosts file

Here’s a sample hosts file that contains mappings for the Finance tenant for nodes with both IPv4 and IPv6 addresses:

192.168.210.16   finance.hcp.example.com
192.168.210.17   finance.hcp.example.com
192.168.210.18   finance.hcp.example.com
192.168.210.19   finance.hcp.example.com
2001:0db8::101   finance.hcp.example.com
2001:0db8::102   finance.hcp.example.com
2001:0db8::103   finance.hcp.example.com
2001:0db8::104   finance.hcp.example.com

URL considerations

The following considerations apply to URLs in management API requests.

URL length

The portion of a URL that follows mapi, excluding any appended query parameters, is limited to 4,095 bytes. If a request includes a URL that violates that limit, HCP returns a status code of 414 (Request URI Too Large).

Percent-encoding for special characters

Some characters have special meaning when used in a URL and may be interpreted incorrectly when used for other purposes. To avoid ambiguity, percent-encode the special characters listed in the table below.

Percent-encoded values are not case sensitive.

CharacterPercent-encoded values
Space%20
Tab%09
New line%0A
Carriage return%0D
+%2B
%%25
#%23
?%3F
&%26
\&5C
Quotation marks with URLs in command lines

When using the HCP management API, you work in a Windows, Unix, or Mac OS X shell. Some characters in the commands you enter may have special meaning to the shell. For example, the ampersand (&) used in URLs to join multiple query parameters may indicate that a process should be put in the background.

To avoid the possibility of the Windows, Unix, or Mac OS X shell misinterpreting special characters in a URL, always enclose the entire URL in double quotation marks.

Authentication

To use the HCPmanagement API, you need either a system-level or tenant-level user account that’s defined in HCP. If HCP is configured to support Windows Active Directory® (AD), you can also use an AD user account that HCP recognizes to access HCP through the metadata query API.

HCP also accepts Active Directory authentication provided through the SPNEGO protocol or the AD authentication header. For more information about SPNEGO, see http://tools.ietf.org/html/rfc4559.

NoteTo use a user account that was created in an HCP release earlier than 4.0, you need to log into the System Management Console or Tenant Management Console, as applicable, with that account at least once before you can use the account with the management API.

You need to provide credentials with every management API request. If you do not provide credentials or provide invalid credentials, HCP responds with a 403 (Forbidden) error message.

To provide credentials in a management API request, you specify an authentication token in an HTTP Authorization request header.

HCP also accepts credentials provided in an hcp-api-auth cookie. However, this method of providing credentials has been deprecated and should not be used in new applications.

HCP authentication through the management API

To authenticate with HCP through the management API, you need to construct an authentication token from a system-level user account or a tenant-level user account and then submit it using a request header with all requests. Successful authentication requires encoding your account information.

Authentication token

An authentication token consists of a username in Base64-encoded format and a password that’s hashed using the MD5 hash algorithm, separated by a colon, like this:

base64-encoded-user-name:md5-hashed-password

For example, here’s the token for the Base64-encoded user name lgreen and the MD5-hashed password p4ssw0rd:

bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20

The GNU Core Utilities include the base64 and md5sum commands necessary to encode your account information. These commands convert text to Base64-encoded and MD5-hashed values, respectively. For more information about the GNU Core Utilities, see http://www.gnu.org/software/coreutils/.

Other tools that generate Base64-encoded and MD5-hashed values are available for download on the web. For security reasons, do not use interactive public web-based tools to generate these values.

The GNU Core Utilities include the base64 and md5sum commands, which convert text to Base64-encoded and MD5-hashed values, respectively. With these commands, a line such as this creates the required token:

echo `echo -n username | base64`:`echo -n password | md5sum` | awk
  '{print $1}'

The character before echo, before and after the colon, and following md5sum is a backtick (or grave accent). The -n option in the echo command prevents the command from appending a new line to the output. This is required to ensure correct Base64 and MD5 values.

Authorization header

You use the HTTP Authorization request header to provide the authentication token for an HCP management API request. The value of this header is HCP followed by the authentication token, in this format:

Authorization: HCP authentication-token

For example, here’s the Authorization header for a user named lgreen and password p4ssw0rd:

Authorization: HCP bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20
Specifying the Authorization header with cURL

With cURL, you use the -H option to specify a header. So, for example, a request to list the tenants for the HCP system named hcp.example.com might look like this:

curl -k -i -H "Authorization: HCP bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20"
    -H "Accept: application/xml"
    "https://admin.hcp.example.com:9090/mapi/tenants"
Specifying the authentication header in Python with PycURL

In Python with PycURL, you use the HTTPHEADER option to specify a header, as in this example:

curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
    bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20"])

Active Directory user authentication through the HCP management API

To authenticate to HCP with Active Directory, you need to construct an authentication token from a AD user account and then submit it using a request header with all requests. The username and password do not need to be encoded.

Active Directory authentication token

An AD authentication token consists of an AD username and password separated by a colon, like this:

AD-username:AD-password

For example, here’s the token for the username lgreen and the password p4ssw0rd:

lgreen@example.com:p4sswOrd

Active Directory authorization header

You use the HTTP Authorization request header to provide the authentication token for an AD user accessing HCP through the management API. The value of this header is AD followed by the authentication token, in this format:

Authorization: AD authentication-token

For example, here’s the Authorization header for a user named lgreen and password p4ssw0rd:

Authorization: AD lgreen@example.com:p4sswOrd
Specifying the Authorization header with cURL

With cURL, you use the -H option to specify a header. So, for example, a request to list the tenants for the HCP system named hcp.example.com might look like this:

curl -i -k -H "Authorization: AD lgreen@example.com:p4sswOrd"
    "Accept: application/xml" "https://admin.hcp.example.com:9090/mapi/tenants"
Specifying the authentication header in Python with PycURL

In Python with PycURL, you use the HTTPHEADER option to specify a header, as in this example:

curl.setopt(pycurl.HTTPHEADER, ["Authorization: AD
    lgreen@example.com:p4sswOrd"])

 

  • Was this article helpful?