Skip to main content
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.

For information on HCP authentication and the URLs you can use with that authentication method, see Alternative authentication method.

NoteWebHelp.png

Notes: 

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. For more information on AD authentication, see Active Directory authentication. For more information on SPNEGO, see http://tools.ietf.org/html/rfc4559.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 (the service point)

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_2018.ppt:

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

https://europe.hcp.example.com/finance/Q4_2018.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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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_2018.ppt -- -k
     -H "Host: finance.europe.hcp.example.com"
     "https://192.168.210.16/quarterly_rpts/Q4_2018.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_2018.ppt -- -k
     -H "Host: europe.hcp.example.com"
     "https://192.168.210.16/finance/quarterly_rpts/Q4_2018.ppt"

For information on HCP nodes, see HCP nodes. For information on when to use an IP address instead of a hostname, see Hostname and IP address considerations.

For the IP addresses of the HCP nodes, contact your tenant administrator.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Using a hosts file


Typically, the HCP system uses DNS for system addressing. If this is not the case, to access the system, you need to provide mappings of the hostname of each target tenant or bucket to one or more node IP addresses.

You specify hostname mappings in the hosts file on the client. The location of this 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

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.

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.

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 on 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 the hosts file to access the system through the S3 compatible API.

Sample hosts file

Here’s a sample hosts file that contains mappings at the tenant and bucket levels:

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

# bucket-level mappings
192.168.210.16          finance.europe.hcp.example.com hr.europe.hcp.example.com
192.168.210.17          finance.europe.hcp.example.com hr.europe.hcp.example.com
192.168.210.18          finance.europe.hcp.example.com hr.europe.hcp.example.com
192.168.210.19          finance.europe.hcp.example.com hr.europe.hcp.example.com

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 on 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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 is the Base64-encoded username for your user account.

signature is 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.

For more information on signatures, see Signatures. For information on changing the password for your user account, see Changing your password.

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

Authorization: AWS bGdyZWVu:vQ/rj3y0AUjWsht9M5aQw4+D0dA=

For information on providing credentials for AWS Version 4 authentication, see http://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html.

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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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-username:ad-password

In this format:

ad-username is the AD user account username.

ad-password is the AD user account password.

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

Authorization: AD lgreen@example.com:p4sswOrd

NoteWebHelp.png

Note: You cannot use AD authentication with S3 compatible requests to create a bucket.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 is the Base64-encoded username for your user account.

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

signature is 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.c...terly_rpts/Q4_2018.ppt
     ?AWSAccessKeyId=bGdyZWVu&Expires=1363867332
     &Signature=eY9lpX2KXRuW%2FrzLYU%2F5jXfjHj7%3D

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 on 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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

NoteWebHelp.png

Note: If 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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 username.

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 username but can also be due to other errors.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Changing your password


If you have a user account that’s defined in HCP, 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 instructions below are for using the Namespace Browser to change your password.

To change your password:

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, in this format:

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

For example:

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

Either of these happens:

oIf the tenant doesn’t support AD authentication of if the tenant supports AD authentication but the namespace doesn’t support AD single sign-on, the Namespace Browser login page appears.

oIf the tenant supports AD authentication and the S3 compatible API is configured to support AD single sign-on, a message appears indicating that single sign-on was not possible.

In this case, you need to click on the Console login page link in the message to display the Namespace Browser login page.

3.On the Namespace Browser login page:

oIn the Username field, type your username.

oIn the Password field, type your case-sensitive password.

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

4.Click on Log In.

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

6.On the Change Password page:

oIn the Existing Password field, type your current password.

oIn the New Password field, type your new password. Passwords must be from one through 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.

The minimum length for passwords is tenant specific. Typically, it’s six or eight characters.

When changing your password, you cannot reuse your current password.

oIn the Confirm New Password field, type your new password again.

7.Click on Update Password.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

 

  • Was this article helpful?