Skip to main content

We've Moved!

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

Access and authentication

The Hitachi API for Amazon S3 is an HTTP-based API. This means that you use URLs to identify tenants, buckets, and objects. Every S3 compatible request for access to HCP must include the URL for the service point, bucket, or object that’s the target of the request.

With every S3 compatible request, you also need to either provide credentials for the user account you’re using or request anonymous access. If HCP determines that credentials you provide correspond to a valid user account and that the user account has the applicable permissions for the requested operation, you become an authenticated user.

HCP supports three methods of user authentication for the S3 compatible API: Amazon Web Services (AWS), Active Directory (AD), and HCP. With AWS authentication, HCP follows the Amazon S3 method of authenticating users. With AD authentication, HCP authenticates users with AD. With HCP authentication, HCP uses its own standard method. If you’re using the S3 compatible API to develop applications that are compatible with Amazon S3, you should use AWS authentication.

This section of the Help describes the URLs you can use in S3 compatible requests when using AWS or AD authentication. It also explains how to provide credentials or request anonymous access with that authentication method.

Note
  • All the examples of S3 compatible requests in this book assume AWS authentication.
  • To use a recognized Active Directory user account for access to HCP through the S3 compatible API, applications can use AWS authentication with the AD identifier. Alternatively, they can use the SPNEGO protocol to negotiate the AD user authentication themselves.

URLs for access to HCP

With the S3 compatible API, the service point (also called the endpoint) is a tenant. Every request you make to access HCP using the S3 compatible API is made within the context of a tenant.

The URL in a request identifies the target of the request. This target can be the tenant, a bucket within the tenant, or an object within a bucket within the tenant. The format you use for a URL depends on the target of the request and the authentication method being used.

An HCP system can have multiple tenants and, therefore, multiple service points. Each tenant has its own default configuration settings for new buckets. Buckets, therefore, can have different characteristics depending on the tenants within which you create them.

Each tenant also has its own set of user accounts. For access that requires you to be an authenticated user, you need to use a user account that’s defined for the applicable tenant.

Targeting a tenant

In an S3 compatible request that uses AWS authentication, if the target is a tenant, you use a URL in this format:

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

Here’s an example in which the tenant name is europe:

https://europe.hcp.example.com

Targeting a bucket

In an S3 compatible request that uses AWS authentication, if the target is a bucket, you use a URL in either of these formats:

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

In the first format above, the bucket name is part of the hostname. In the second format, the bucket name follows the hostname.

Here’s are examples in which the tenant name is europe and the bucket name is finance:

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

Targeting an object

In an S3 compatible request that uses AWS authentication, if the target is an object, you use a URL in either of these formats:

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

In the first format above, the bucket name is part of the hostname. In the second format, the bucket name follows the hostname.

Here are examples in which the tenant name is europe, the bucket name is finance, and the object name is Q4_2019.ppt:

https://finance.europe.hcp.example.com/Q4_2019.ppt
https://europe.hcp.example.com/finance/Q4_2019.ppt

Using SSL security

When you create a bucket or list the buckets you own, HCP does not require the use of SSL security with the S3 compatible request; that is, you can start the URL in the request with either HTTP or HTTPS. Whether the use of SSL security with other S3 compatible requests is required, optional, or not supported depends on the configuration of the S3 compatible API for the target bucket.

By default, the use of SSL security is optional for requests for operations other than creating a bucket or listing the buckets you own. You cannot use the S3 compatible API to change this configuration. However, tenant administrators can use other HCP interfaces to reconfigure the S3 compatible API to require or not support the use of SSL security.

Using an IP address in a URL

Normally, you let HCP choose the node on which to process an S3 compatible API request. You can, however, use an IP address in the request 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 an HCP node.

When you use an IP address in a URL, you also need to specify the fully qualified hostname in an HTTP Host request header.

Here’s an example of an s3curl command that uses a URL with an IP address and a Host header that identifies the finance bucket:

./s3curl.pl --id=lgreen --put=Q4_2019.ppt -- -k
     -H "Host: finance.europe.hcp.example.com"
     "https://192.168.210.16/quarterly_rpts/Q4_2019.ppt"

Here’s a command that does the same thing as the command above but uses the format in which the bucket name follows the URL:

./s3curl.pl --id=lgreen --put=Q4_2019.ppt -- -k
     -H "Host: europe.hcp.example.com"
     "https://192.168.210.16/finance/quarterly_rpts/Q4_2019.ppt"

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 S3 compatible API requests.

Case sensitivity in URLs

In the URLs you specify in S3 compatible requests:

  • HTTP and HTTPS are not case sensitive.
  • Hostnames are not case sensitive.
  • Bucket names are not case sensitive.
  • Unlike the items above, object names are case sensitive.
Quotation marks with URLs in command lines

When using a command-line tool to access HCP through the S3 compatible API, you work in a Unix, Mac OS X, or Windows 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 also often indicates that a process should be put in the background.

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

Disabling SSL certificate verification

If you’re using HTTPS in your request URLs, check with your tenant administrator as to whether you need to disable SSL certificate verification. You would need to do this if the SSL server certificate presented by the HCP system is not signed by a trusted certificate authority.

With s3curl, you disable SSL certificate verification by including ‑k or ‑‑insecure in the request command line.

Authentication

To use the S3 compatible API as an authenticated user, you need to provide credentials. These credentials must be based on the username and password for your HCP user account or, if HCP is configured to support Windows Active Directory® (AD), for an AD user account that HCP recognizes.

To provide credentials, you typically use the HTTP Authorization request header. However, HCP also accepts Active Directory authentication provided through the SPNEGO protocol. For more information about SPNEGO, see http://tools.ietf.org/html/rfc4559.

If the S3 compatible API is configured to require user authentication, you need to provide credentials with every request. If the S3 compatible API is configured to allow anonymous access, you need to either provide credentials or request anonymous access with each request.

HCP supports presigned URLs. A presigned URL uses query parameters to provide credentials. Presigned URLs allow you to temporarily share objects with other users without the need to grant those users permission to access your buckets or objects. Presigned URLs are compatible only with the AWS method of authentication.

AWS authentication

To provide credentials for AWS Version 2 authentication, you use the Authorization request header with a value in the format shown below:

Authorization: AWS access-key:signature

In this format:

  • access-key

    The Base64-encoded username for your user account.

  • signature

    A value calculated using your secret key and specific elements of the S3 compatible request, including the date and time of the request. Your secret key is the MD5-hashed password for your user account.

    Because the signature for an S3 compatible request is based on the request contents, it differs for different requests.

Here’s an example of an Authorization header for AWS Version 2 authentication:

Authorization: AWS bGdyZWVu:vQ/rj3y0AUjWsht9M5aQw4+D0dA=

With AWS Version 4 authentication, the S3 compatible API supports both signed and unsigned payloads.

Active Directory authentication

To provide credentials for Active Directory authentication, you use the Authorization request header with a value in the format shown below:

Authorization: AD ad-user-name:ad-password

In this format:

  • ad-username

    The AD user account username.

  • ad-password

    The AD user account password.

Here’s an example of an Authorization header for AD authentication:

Authorization: AD lgreen@example.com:p4sswOrd
NoteYou cannot use AD authentication with S3 compatible requests to create a bucket.

Presigned URLs

To provide credentials for AWS authentication using a presigned URL, you append these query parameters to the request URL:

AWSAccessKeyId=access-key
Expires=expiration-time
Signature=signature

In these parameters:

  • access-key

    The Base64-encoded username for your user account.

  • expiration-time

    The time the request expires, in seconds since January 1, 1970, at 00:00:00 UTC.

  • signature

    A value calculated using your secret key and specific elements of the S3 compatible request, including the date and time the request expires.

If any part of a presigned URL is changed, the URL becomes invalid.

Here’s an example of a presigned URL:

https://finance.europe.hcp.example.com/quarterly_rpts/Q4_2019.ppt
     ?AWSAccessKeyId=bGdyZWVu&Expires=1363867332
     &Signature=eY9lpX2KXRuW%2FrzLYU%2F5jXfjHj7%3D

Signatures

Third-party tools that are compatible with the S3 compatible API typically calculate request signatures automatically. Some of these tools can also be used to generate presigned URLs.

If you’re writing your own application, you can use an AWS SDK to calculate request signatures. For information about these SDKs, see: http://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingAcctOrUserCredentials.html

For detailed information on calculating signatures for AWS authentication, see: http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html

Anonymous access

To request anonymous access to a bucket or object, you use the Authorization request header with the AWS authentication format. However, instead of providing credentials for a user account, you specify all_users in place of the access key and leave the signature blank, like this:

Authorization: AWS all_users:

The colon after all_users is required.

NoteIf the bucket you are trying to access is configured to support single sign-on with Active Directory (AD), anonymous requests to access that bucket or objects in that bucket fail.

Invalid credentials

Regardless of how the S3 compatible API is configured, if you provide invalid credentials, HCP returns an InvalidAccessKeyId or SignatureDoesNotMatch error code and does not perform the requested operation:

  • InvalidAccessKeyId

    Indicates that the access key you provided does not correspond to a valid user name.

  • SignatureDoesNotMatch

    Indicates that the signature does not match the content of the request. This can happen if the secret key used in the signature calculation does not correspond to the password for the account with the applicable user name but can also be due to other errors.

Changing your password

If you have an HCP user account, the password for the account is initially set by a tenant administrator. You can change this password at any time, as long as you have browse or read permission for at least one bucket. For security purposes, you should change your password as soon as possible after you receive your account information.

Your password is used to calculate your secret key for use with the S3 compatible API. When you change your password, your secret key also changes.

You can use a few different HCP interfaces to change your password, as long as you have access to those interfaces. When you change your password in one interface, it changes for all HCP interfaces to which you have access.

The next procedure describes how to change your password using the Namespace Browser.

Procedure

  1. Open a web browser window.

  2. In the address field, enter the URL for a bucket for which the S3 compatible API requires user authentication and for which you have browse or read permission. Use this format:

    http[s]://bucket-name.tenant-name.hcp-domain-name/browser
    For example:
    https://finance.europe.hcp.example.com/browser
    Either of these events happen:
    • If the tenant does not support AD authentication or the tenant supports AD authentication but the namespace does not support AD single sign-on, the Namespace Browser login page is displayed.
    • If the tenant supports AD authentication and the S3 compatible API is configured to support AD single sign-on, a message is displayed indicating that single sign-on was not possible.

      Click the Console login page link in the message to display the Namespace Browser login page.

  3. On the Namespace Browser login page:

    1. In the Username field, type your username.

    2. In the Password field, type your case-sensitive password.

    3. In the Domain field, if present, select the domain name of the HCP system.

  4. Click Log In.

  5. In the top right corner of the Namespace Browser window, click the Password link.

  6. On the Change Password page:

    1. In the Existing Password field, type your current password.

    2. In the New Password field, type your new password.

      Passwords can be up to 64 characters long, are case sensitive, and can contain any valid UTF-8 characters including white space. To be valid, a password must include at least one character from two of these three groups: alphabetic, numeric, and other. When changing your password, you cannot reuse your current password.
    3. In the Confirm New Password field, type your new password again.

  7. Click Update Password.

 

  • Was this article helpful?