Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Access and authentication

With the HCP metadata query API, each request you make must specify a URL that represents an HCP tenant, the default tenant, or all tenants to which system-level users have access. Each request must also include the credentials for the user account you’re using to access namespaces through the metadata query API. Your user account determines which namespaces you can access.

This chapter describes request URLs and explains how to include account credentials in a metadata query API request.

The examples in this book use cURL and Python with PycURL, a Python interface that uses the libcurl library. cURL and PycURL are both freely available open-source software. You can download them from http://curl.haxx.se.

Request URL

The URL format in a metadata query API request depends on whether you use a hostname or IP address to connect to the HCP system and on the namespaces you want to query.

Connecting using a hostname

When connecting to HCP using a hostname, the URL format you use depends on the namespaces you are querying:

One or more namespaces owned by an HCP tenant

To query one or more namespaces owned by an HCP tenant, use this format:

http[s]://hcp-tenant-name.hcp-domain-name/query

For example:

https://europe.hcp.example.com/query

To use this format, you need either a tenant-level user account or, if the tenant has granted system-level users administrative access to itself, a system-level user account. In either case, the account must be configured to allow use of the metadata query API.

When you use a tenant-level user account, HCP returns results only for objects in namespaces for which the tenant-level user has search permission.

Unlike with requests to the /rest interface, you do not specify a namespace in this URL.

Only the default namespace

To query only the default namespace, use this format:

https://default.hcp-domain-name/query

For example:

https://default.hcp.example.com/query

o use this format, you need a system-level user account that’s configured to allow the user to use the metadata query API.

For this URL format, you need to use HTTP with SSL security (HTTPS). If the query specifies HTTP instead of HTTPS in the URL, HCP returns a 403 (Forbidden) error.

Entire repository

To query the entire repository (that is, both the default namespace and all namespaces owned by each tenant that has granted system-level users administrative access to itself), use this format:

https://admin.hcp-domain-name/query

For example:

https://admin.hcp.example.com/query

To use this format, you need a system-level user account that ‘s configured to allow use of the metadata query API.

For this URL format, you need to use HTTP with SSL security (HTTPS). If the query specifies HTTP instead of HTTPS in the URL, HCP returns a 403 (Forbidden) error.

Considerations

The following considerations apply to these URLs:

  • The URL must specify query, in all lowercase, as the first element following the hostname in the URL.
  • If the URL specifies HTTPS and the HCP system uses a self-signed SSL server certificate, the request must include an instruction not to perform SSL certificate verification. With cURL, you do this by including the -k option in the request command line. In Python with PycURL, you do this by setting the SSL_VERIFYPEER option to false.

Connecting using an IP address

The core hardware for an HCP system consists of servers, called nodes, that are networked together. When you access an HCP system, your point of access is an individual node. Typically, you let HCP choose the node on which to process a metadata query 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 hostname in the URL with the IP address of the node you want:

https://node-ip-address/query

With this URL format, you can provide an HTTP Host header that specifies a fully qualified hostname for a tenant or the entire repository. The hostname format you use depends on the namespaces you want to query:

  • To query namespaces owned by an HCP tenant, use this format:
    hcp-tenant-name.hcp-domain-name
  • To query only the default namespace, use this format:
    default.hcp-domain-name
  • To query the entire repository, use this format:
    admin.hcp-domain-name

If you omit the Host header, the request queries the entire repository.

NoteThe Host header is required when you are performing an operation-based query and the request body specifies a namespace.

With cURL, you use the -H option to provide the Host header. 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: default.hcp.example.com”])

When using an IP address in a URL, you need to use HTTP with SSL security.

NoteIf you don’t know the IP addresses for the HCP system, contact your HCP system administrator.

Connecting using a hosts file

All operating systems have a hosts file that contains mappings from hostnames to IP addresses. If the HCP system does not support DNS, you can use this file to enable access to tenants by hostname.

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/host
Hostname mappings

Each entry in a hosts file maps one or more fully qualified hostnames to a single IP address. For example, the entry below maps the hostname of the europe tenant in the HCP system named hcp.example.com to the IP address 192.168.210.16:

192.168.210.16 europe.hcp.example.com

The following considerations apply to hosts file entries:

  • Each entry must appear on a separate line.
  • Multiple hostnames in a single line must be separated by white space. With some versions of Windows, these must be single spaces.
  • At the system-level, the fully qualified hostname includes admin.
  • Each hostname can map to multiple IP addresses.

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.

NoteIf you don’t know the IP addresses for the HCP system, contact your HCP system administrator.
Hostname mapping considerations

You can map a hostname to any number of IP addresses. The way multiple mappings are used depends on the client platform. For information about how your client handles multiple mappings in a hosts file, 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 Management Console.

Sample hosts file entries

Here’s a sample hosts file that contains mappings for the repository as a whole and the europe tenant:

# HCP system-level mappings
192.168.210.16 admin.hcp.example.com
192.168.210.17 admin.hcp.example.com

# tenant-level mappings
192.168.210.16 europe.hcp.example.com
192.168.210.17 europe.hcp.example.com

Authentication

To use the metadata query management 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), applications can also use an AD user account that HCP recognizes to access HCP through the metadata query API.

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

With each metadata query API request, you need to provide your account credentials in the form of a username and password. If you do not provide credentials or provide invalid credentials, HCP responds with a 403 (Forbidden) error message.

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

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

HCP authentication through the metadata query management API

To authenticate with HCP through the metadata query 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 metadata query management API

To authenticate with 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 does 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?