Security
The System Management application supports configuring system security features, including user authentication.
Granting access to users
These are the general steps you need to take to grant users access to the system:
- Add one or more identity providers to the system.
- Add one or more groups from your identity providers to the system.
- Create a role that contains the system permissions you want to associate with a group of users.
- Associate roles with groups.
Setting the session timeout limit
You can use the Admin App, CLI commands, or REST API methods to set the system session timeout limit. This limit affects user sessions in all applications that your system runs and also affects the length of time that REST API authorization tokens are valid.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Settings tab, type a number of minutes in the Session Timeout field.
Click Update.
Related CLI commands
editSecuritySettings
Related REST API methods
PUT /security/settings
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Setting the refresh token timeout limit
You can use the Admin App, CLI commands, or REST API methods to set the refresh token timeout limit. The refresh token timeout limit must be greater than the session timeout limit so that if the access token expires, the refresh token will still be active and you can request a new session token. When your refresh token expires, you will need to resubmit your credentials to access your system.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Settings tab, type a number of minutes in the Refresh Token Timeout field.
Click Update.
Related CLI commands
editSecuritySettings
Related REST API methods
PUT /security/settings
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Setting the CORS Allowed Origins
You can use the Admin App, CLI commands, or REST API methods to set CORS (cross-origin resource sharing) origins that are allowed on your system. Specifying multiple origins allows you to access restricted resources.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Settings tab, type a list of origins in the CORS Allowed Origins field.
Click Update.
Related CLI commands
editSecuritySettings
Related REST API methods
PUT /security/settings
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Identity providers
The system supports these identity provider types for user authentication:
- Active Directory (AD)
- OpenLDAP
- 389 Directory Server
- LDAP Compatible: Other LDAP-compatible identity providers not listed above.
To use one of these systems to authenticate users with your system, you need to first add your identity provider to the system.
Adding identity providers
Procedure
Select the Configuration window.
Click Security.
On the Identity Providers tab, click Create.
Select and configure an identity provider type.
Click Create.
Related CLI commands
createIdentityProvider
Related REST API methods
POST /security/identityProviders
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Identity provider configuration settings
The following sections describe the configuration settings for each type of identity provider that the system supports.
Security Realm Name: The name by which to identify this identity provider in the system. The name appears as an option in the Security Realm list on Admin App login pages.
- Identity Provider Hostname: Host name or IP address for the identity provider.
- Transport Security: The protocol to use for securing communications between the system and the identity provider. Options are:
- None
- TLS Security (Transport Layer Security)
- Use Suffix For Hostname Verification: When enabled, if the client host name doesn’t match the certificate host name, host name verification will instead verify whether the ending of the client host name matches the provided suffix. WARNINGThis option can impact security and should only be enabled if the client host name is expected to differ from the certificate host name.
- Hostname Suffix: The suffix used for host name verification if the default host name verification fails.
- Use Suffix For Hostname Verification: When enabled, if the client host name doesn’t match the certificate host name, host name verification will instead verify whether the ending of the client host name matches the provided suffix.
- SSL (Secure Sockets Layer)
NoteWhen selecting TLS Security, the setting Use Suffix For Hostname Verification appears. - Identity Provider Host Port: Network port used to communicate with the identity provider. The default value depends on the Transport Security setting:
- For None or TLS Security (Transport Layer Security), 389
- For SSL (Secure Sockets Layer), 636
- User Name: A user account on the identity provider. The system uses this user account to read information from the identity provider.
- Password: The user account password.
- Domain: The AD domain in which the user account is defined. NoteUse the short name for the AD domain. For example, use
MYACTIVEDIRECTORYinstead ofMYACTIVEDIRECTORY.local. - Search Base DN: The distinguished name (DN) of the identity provider location where you want the system to begin its searches for users and groups.
For example, if you specify a value of OU=Users,DC=corp,DC=example,DC=com, the system searches for users and groups in the organization unit called Users in the corp.example.com domain.
- Default Domain Name: The default domain for users logging into the Admin App and Search App. For example, if you specify a default domain name of east.example.com, the user jdoe@east.example.comneeds to specify only jdoe when logging into either app.
- Identity Provider Hostname: Host name or IP address for the identity provider.
- Transport Security: The protocol to use for securing communications between the system and the identity provider. Options are:
- None
- TLS Security (Transport Layer Security)
- Use Suffix For Hostname Verification: When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix. WARNINGThis option can impact security and should only be enabled if the client host name is expected to differ from the certificate host name.
- Hostname Suffix: The suffix used for host name verification if the default host name verification fails.
- Use Suffix For Hostname Verification: When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix.
- SSL (Secure Sockets Layer)
- Identity Provider Host Port: Network port used to communicate with the identity provider. The default value depends on the Transport Security setting:
- For None or TLS Security (Transport Layer Security), 389
- For SSL (Secure Sockets Layer), 636
- User Name: A user account on the identity provider. Your system uses this account to read information from the identity provider.
- Password: The user account password.
- User DN Template: A template on the LDAP server. When a user logs into their system, the provided username is inserted into this template to determine the user's LDAP distinguished name (DN).
- Unique ID: The unique identifier for the specified LDAP server.
- Member Name Attribute: The name of the attribute that each group on the identity provider uses to list its members.
- Search Base DN: The distinguished name (DN) of the identity provider location where you want the system to begin searching for users and groups.
For example, if you specify a value of OU=Users,DC=corp,DC=example,DC=com, the system searches for users and groups in the organization unit called Users in the corp.example.com domain.
- Group Object Class: The objectClass value for groups on the LDAP server.
- Identity Provider Hostname: Host name or IP address for the identity provider.
- Transport Security: The protocol to use for securing communications between the system and the identity provider. Options are:
- None
- TLS Security (Transport Layer Security)
- Use Suffix For Hostname Verification: When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix. WARNINGThis option can impact security and should only be enabled if the client host name is expected to differ from the certificate host name.
- Hostname Suffix: The suffix used for host name verification if the default host name verification fails.
- Use Suffix For Hostname Verification: When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix.
- SSL (Secure Sockets Layer)
- Identity Provider Host Port: Network port used to communicate with the identity provider. The default value depends on the Transport Security setting:
- For None or TLS Security (Transport Layer Security), 389
- For SSL (Secure Sockets Layer), 636
- User Name: A user account on the identity provider. Your system uses this account to read information from the identity provider.
- Password: The user account password.
- User DN Template: A template on the LDAP server. When a user logs into their system, the provided username is inserted into this template to determine the user's LDAP distinguished name (DN).
- Unique ID: The unique identifier for the specified LDAP server.
- Member Name Attribute: The name of the attribute that each group on the identity provider uses to list its members.
- Search Base DN: The distinguished name (DN) of the identity provider location where you want the system to begin searching for users and groups.
For example, if you specify a value of OU=Users,DC=corp,DC=example,DC=com, the system searches for users and groups in the organization unit called Users in the corp.example.com domain.
User information caching
The system caches the following information from each of your identity providers:
- The names of users who access the system.
- The groups that each user belongs to.
As long as this information is in the system's cache, your users can perform any activities for which they have permissions, without the system needing to reconnect to the identity provider.
LDAP user information remains in the cache for four hours.
Any changes that you make on the identity provider are not reflected in the system until the information is removed from the cache. For example, if you add a user to an LDAP identity provider, that user cannot access the system for up to four hours, or until the cache is cleared. If you delete a user from an LDAP identity provider, that user will be able to access the system for up to four hours, or until the cache is cleared.
To ensure that a change is reflected immediately, use the clearCache command or API.
Related CLI commands
clearCache
Related REST API methods
POST /security/clearCache
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Viewing identity providers
You can use the Admin App, CLI commands, or REST API methods to view the identity providers that have been added to your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Identity Providers tab.
Related CLI commands
getIdentityProvider
listIdentityProviders
Related REST API methods
GET /security/identityProviders/{uuid}
GET /security/identityProviders
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Deleting identity providers
When you delete an identity provider from your system, all users from that provider lose access to the system.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Identity Providers tab, click the delete icon (
) for the server you want to remove.
Related CLI commands
deleteIdentityProvider
Related REST API methods
DELETE /security/identityProviders/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Groups
To allow user access to your system, you need to add groups to your system. These groups are defined on your organization's identity providers. After you add a group to your system, you can specify what roles its members have.
Adding groups
You use the Admin App, CLI commands, or REST API methods to add groups from your identity providers to your system.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Groups tab, click Create.
Select an identity provider and type a string on which to query the identity provider for groups.
Click Discover Groups.
Click Continue.
Select one or more roles to associate with the group.
Click Create.
Related CLI commands
createGroup
Related REST API methods
POST /security/groups
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Viewing groups
You use the Admin App, CLI commands, or REST API methods to view all the groups that have been created for your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Groups tab.
Related CLI commands
getGroup
listGroups
Related REST API methods
GET /security/groups/{uuid}
GET /security/groups
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Assigning roles to groups
You use the Admin App, CLI commands, or REST API methods to assign roles to the groups that you've added your system.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Groups tab, select the group you want to edit.
On the Roles tab, select one or more roles to enable for the group.
Click Update.
Related CLI commands
editGroup
Related REST API methods
PUT /security/groups/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Deleting groups
When you delete a group, all users in the group lose access to your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Groups tab.
Click the delete icon (
) for the group you want to remove.
Related CLI commands
deleteGroup
Related REST API methods
DELETE /security/groups/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Roles
Roles determine what actions a group of users can perform. You create your own roles, each of which can grant permission to perform any combination of actions.
Creating roles
You can use the Admin App, CLI commands, or REST API methods to create roles and select which permissions the roles contain.
Each permission in a role grants a user the ability to perform an action in some area of the system. For example, the admin:services:read permission grants the ability to view services through the Admin App.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Roles tab, click Create.
Specify a name and, optionally, a description for the role.
Use the Individual and Wildcard tabs to edit the permissions for the role.
On the Individual tab, you can enable individual permissions or categories of permissions:- Select a category of permissions and select one or more individual permissions within the category.
For example, with the permissions selected in this image, a user can read, create, and update certificates, but cannot delete them.
- On the Wildcard tab, you can enable permissions for multiple categories at the same time. To do this:
- Click Add Permission.
- Use the menus to select a category of permissions.
- Leave the last menu set to the wildcard character (*).
- Select a category of permissions and select one or more individual permissions within the category.
Click Create.
Click Update.
Related CLI commands
createRole
Related REST API methods
POST /security/roles
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Viewing roles
You can use the Admin App, CLI commands, or REST API methods to view all the roles that have been created for your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Roles tab.
Related CLI commands
getRole
listRoles
Related REST API methods
GET /security/roles/{uuid}
GET /security/roles
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Editing roles
You can use the Admin App, CLI commands, or REST API methods to change the permissions that a role contains.
Each permission in a role grants a user the ability to perform an action in some area of the system. For example, the permission admin:services:read grants the ability to view services through the Admin App.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Roles tab.
Select the role you want to edit.
Use the Individual and Wildcard tabs to edit the permissions for the role.
On the Individual tab, you can enable individual permissions or categories of permissions:- Select a category of permissions and select one or more individual permissions within the category.
For example, with the permissions selected in this image, a user can read, create, and update certificates, but cannot delete them.
- On the Wildcard tab, you can enable permissions for multiple categories at the same time. To do this:
- Click Add Permission.
- Use the menus to select a category of permissions.
- Leave the last menu set to the wildcard character (*).
- Select a category of permissions and select one or more individual permissions within the category.
Click Create.
Click Update.
Related CLI commands
editRole
Related REST API methods
PUT /security/roles/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Deleting roles
When you delete a role, all groups associated with that role lose the permissions that the role granted.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Roles tab.
Click the delete icon (
) for the role you want to remove.
Related CLI commands
deleteRole
Related REST API methods
DELETE /security/roles/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Permissions
The following tables list the HCP for cloud scale permissions available for system roles. The words Yes and No indicate whether or not the permission is assigned for a default role.
The set permissions override corresponding get permissions. That is, if a user has permission to set (configure) a function, the user is also granted permission to get (view) the function.
| Chargeback Reporting | ||
| Permission name | Description | Default admin role permission? |
| chargeback:system:get_report | Generate chargeback report for any bucket | Yes |
| chargeback:user:get_report | Generate chargeback report for the user's buckets | Yes |
| Data Service | ||
| Permission name | Description | Default admin role permission? |
| data:bucket:expirationlifecycle:get | View bucket expiration lifecycle policy configuration | Yes |
| data:bucket:expirationlifecycle:set | Configure bucket expiration lifecycle policy | Yes |
| data:bucket:notification:get | View bucket notification configuration | Yes |
| data:bucket:notification:set | Configure bucket notification | Yes |
| data:bucket:objectlock:get | View bucket object lock policy configuration | Yes |
| data:bucket:objectlock:set | Configure bucket object lock policy | Yes |
| data:bucket:sync:from:set | Create bucket sync-from rules for buckets the user owns or has access to | Yes |
| data:bucket:sync:get | View bucket sync-from and sync-to rules for buckets the user owns or has access to | Yes |
| data:bucket:sync:to:set | Create bucket sync-to rules for buckets the user owns or has access to | Yes |
| License | ||
| Permission name | Description | Default admin role permission? |
| mapi:license:add | Add licensed feature | Yes |
| mpi:license:list | List all licensed feature | Yes |
| MAPI Alerts | ||
| Permission name | Description | Default admin role permission? |
| mapi:alert:list | List all active alerts | Yes |
| MAPI S3 Settings | ||
| Permission name | Description | Default admin role permission? |
| mapi:s3_settings:get | Read S3 settings | Yes |
| mapi:s3_settings:set | Modify S3 settings | Yes |
| MAPI Storage Component | ||
| Permission name | Description | Default admin role permission? |
| mapi:storage_component:activate | Activate a storage component | Yes |
| mapi:storage_component:get_capacity | Get storage component capacity | Yes |
| mapi:storage_component:create | Create a storage component | Yes |
| mapi:storage_component:list | List storage component(s) | Yes |
| mapi:storage_component:test | Test a storage component | Yes |
| mapi:storage_component:update | Modify a storage component | Yes |
| mapi:storage_component:update_state | Modify state of a storage component | Yes |
| MAPI Stored Objects | ||
| Permission name | Description | Default admin role permission? |
| mapi:client_object:lookup | List stored objects | Yes |
| MAPI System | ||
| Permission name | Description | Default admin role permission? |
| mapi:certificates:refresh | Refresh SSL certificates | |
| mapi:system:info | List system information | Yes |
| MAPI User | ||
| Permission name | Description | Default admin role permission? |
| mapi:user:list | List existing users | Yes |
| mapi:user:list_buckets | List user's buckets | Yes |
| mapi:user:revoke_credentials | Revoke S3 credentials | Yes |
| mapi:user:revoke_tokens | Revoke OAuth tokens | Yes |
| S3 Encryption Setting | ||
| Permission name | Description | Default admin role permission? |
| mapi:s3_encryption:get | Read S3 encryption settings | Yes |
| mapi:s3_encryption:set | Enable global encryption | Yes |
| mapi:s3_encryption:unseal | Unseal KMS service | Yes |
| S3 User | ||
| Permission name | Description | Default admin role permission? |
| s3:user:generate_credentials | Generate S3 credentials | Yes |
| Serial Number | ||
| Permission name | Description | Default admin role permission? |
| mapi:serial_number:get | Read serial number | Yes |
| mapi:serial_number:set | Modify serial number | Yes |
Revoking user account credentials
To immediately and completely revoke a user's account credentials, it's best to remove credentials from the identity provider, clear the HCP for cloud scale user cache, revoke OAuth tokens, and revoke S3 credentials, in that order.
You might want to revoke a user's account credentials for a number of reasons:
- The user has left the organization.
- The user is part of a company that has ended a contract with the organization.
- The user had a temporary account that has expired.
Before you begin
To complete these tasks you must have permission to reset a user's password in the identity provider (IdP), such as Active Directory or LDAP, and you must have permission to execute HCP for cloud scale API methods.
If you remove the user account from the IdP, you might not be able to move or delete the user's data and buckets. If you must do that, reset the account password instead, delete or move the data as needed, and then remove or disable the account.
Procedure
Prevent the user from signing in through the IdP.
- Remove or disable the user account in the IdP.
- Change or remove the user's password.
Clear the HCP for cloud scale user cache:
Obtain an OAuth token.
Use the API method
POST security/clearCache.
Revoke the user's OAuth tokens.
Obtain an OAuth token (or use the token previously obtained).
Obtain an XSRF token.
Use the API method
The response body contains the user ID.POST user/listto obtain the user ID for the user.Use the API method
You should receive a 200 OK response with an empty response body.POST user/revoke_tokens, passing as a parameter the user ID previously obtained.
Revoke the user's existing S3 credentials.
(Alternatively, you can generate fresh S3 credentials, but the listed steps create a positive record of revocation.)Obtain an OAuth token (or use the token previously obtained).
Obtain an XSRF token (or use the token previously obtained).
Use the API method
POST user/listto obtain the user ID for the user (or use value previously obtained).Use the API method
You should receive a 200 OK response with an empty response body.POST user/revoke_credentials, passing as a parameter the user ID previously obtained.
Results
Next steps
- Remove all objects, versions, and delete markers in each of the user's buckets. When the buckets are empty, remove them.
- Set an expiration period of one second in each of the user's buckets. When the buckets are empty, remove them.
Changing a local user's account password
Your system includes a single local user account called admin, which is available when you first install the system. In addition, your system lets you create a secondary local admin account for reconciliation purposes. You can use the Admin App, CLI commands, or REST API methods to change the passwords for these accounts.
Procedure
Click the user icon (
) in the top right corner of the window.Click Change Password.
Confirm your current password for the chosen account and specify a new password.
Click Change Password.
Related CLI commands
updateCurrentUserPassword
Related REST API methods
POST /setup/password
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Certificates
The system uses SSL to provide secure incoming and outgoing communication for the product applications.
To enable SSL security, you need a valid server certificate or chain of certificates for incoming communication and a valid client certificate for outgoing communication.
The system comes with its own self-signed SSL system certificate, which is generated and installed automatically when the system is installed. This certificate is not automatically trusted by web browsers.
You can choose to trust this self-signed system certificate or replace it by doing one of the following:
- Upload a PKCS12 format certificate chain from a certificate authority (CA).
- Download a certificate signing request (CSR) and use it to obtain, upload, and apply a certificate signed by a CA.
- Generate and apply a new self-signed SSL server certificate. You might do this, for example, if the current certificate is close to expiring and you are waiting to retrieve a new one from your CA.
For outgoing communication, such as to storage components, you need to upload the certificate used by clients. However, you don't need to upload the client certificate if it's valid and trusted by a CA.
Viewing installed certificates
You can use the Admin App, CLI commands, or REST API methods to view information about:
- The system certificate. This is the certificate used to secure communications for your system's applications, CLIs, and REST APIs.
- Client certificates. These are the certificates you upload to HCP for cloud scale that allow the system to communicate securely with clients such as AD and storage components.
For each certificate, you can view:
- The distinguished name of the certificate
- The date and time when the certificate goes (or went) into effect
- The date and time when the certificate expires (or expired)
Procedure
Select Dashboard > Configuration.
Click Certificates.
The System tab displays the currently active system certificate.To view the client certificates, select the Client tab.
Related CLI commands
listCertificates
getCertificate
getSystemCertificate
Related REST API methods
GET /certificates
GET /certificates/system
GET /certificates/{subjectDn}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Client certificates
For the HCP for cloud scale system to communicate with Identity Providers (IdPs) and storage components that use SSL-protected communication, the system must accept the certificate from the clients. Your system prompts you to accept a client certificate when testing the connection to an IdP using the System Management application. It's best to use valid SSL certificates trusted by a certificate authority, but you can also upload client certificates manually.
Client certificate considerations
Keep the following in mind when configuring SSL certificates for a client (such as a storage component):
- Do not allow any of the SSL certificates to expire.
- Adhere to the established best practices for setting up SSL certificates.
For information on SSL best practices, see http://tools.ietf.org/html/rfc5280 and http://tools.ietf.org/html/rfc6125.
- When configuring a certificate chain, ensure that all intermediate issuers have the appropriate signing authority permissions so that the entire chain is signed.
- If you regenerate or upload an SSL certificate you must repair (that is, restart) the S3 Gateway and MAPI Gateway services for the change to take effect.
- If you regenerate or upload an SSL certificate for an S3-compatible remote system used for bucket synchronization you must repair (that is, restart) the S3 Gateway and Policy Engine services for the change to take effect.
Retrieving the client certificate for an HCP S Series Node
It's best to use valid SSL certificates from a trusted certificate authority. If an HCP S Series Node storage component uses another kind of certificate, you can retrieve the certificate and upload it manually. This procedure uses the Firefox browser.
Procedure
Go to the HCP S Series Node management interface at
where host is the host name of the management system.https://host:8000/Right click and select Page Info.
Select Security and click View Certificate.
Click the Details tab.
Click Export, select a download location, and click Save.
Results
Next steps
Uploading client certificates manually
If a client such as a storage component does not have a trusted SSL certificate, you can upload it manually.
Procedure
Retrieve the SSL certificate from your client.
In the Admin App, click Configuration.
Click Certificates.
On the Client tab, click Upload Client Certificate.
Drag the certificate file into the Upload Certificate box.
Refresh the certificate by doing one of the following:
- Use the Object Storage Management MAPI method
POST /certificates/refresh - Click Services, select and repair the S3 Gateway service, and then select and repair the MAPI Gateway service.
- Use the Object Storage Management MAPI method
Next steps
Related CLI commands createCertificate
createCertificate
Related REST API methods
POST /certificates (System Management)
POST /certificates/refresh (Object Storage Management)
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Changing the system certificate
By default, your system includes a self-signed certificate when the system is first installed.
You cannot delete the currently installed certificate. However, you can replace the certificate by:
- Installing a new PKCS12 certificate
- Generating and installing a new self-signed certificate
- Generating a certificate signing request (CSR) and installing the certificate you receive in response to this request
System certificate considerations
Keep the following in mind when configuring SSL certificates for your system, especially if you are configuring the system to use one or more certificates that you create yourself:
- Do not allow any of the SSL certificates to expire.
- Adhere to the established best practices for setting up SSL certificates. For example, if you are using wildcards to identify hostnames in an SSL certificate, a wildcard should appear only at the beginning of the hostname, not in the middle.
For information on SSL best practices, see http://tools.ietf.org/html/rfc5280 and http://tools.ietf.org/html/rfc6125.
- Ensure that the DNS name for the system matches the name defined in the certificate. If you rename the system you need a new certificate.
- When configuring a certificate chain, ensure that all intermediate issuers have the appropriate signing authority permissions so that the entire chain is signed.
- If you regenerate or upload an SSL certificate you must repair (that is, restart) the S3 Gateway and MAPI Gateway services for the change to take effect.
- If encryption is enabled you must also repair the Key Management Server service and unseal the vault.
Installing a certificate you created
You can create an SSL server certificate by using a third-party tool such as OpenSSL. When creating the certificate, you specify two passwords, one for the PKCS12 object containing the certificate and one for the private key for the certificate. To use the certificate with the system, these passwords must be the same.
When you create an SSL server certificate, you can have that certificate signed by a certificate authority (CA). In this case, the CA you use might provide you with one or more intermediate certificates. These certificates are used in conjunction with the SSL server certificate you created to establish a certificate chain, which is an ordered list of certificates in which each certificate is trusted by the next.
To preserve the chain of trust among the certificates, you must upload the certificates in the correct order. That is, each certificate you upload must be immediately followed by the certificate that signs it. For information on the correct order for the certificate chain, see the CA.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Click Update System Certificate.
In the box PKCS12 Password, type the password for the certificate.
Drag the certificate into the box Upload Certificate Chain.
Click Continue.
Click Accept.
Restart (repair) the S3 Gateway.
Related CLI commands
uploadPKCS12Certificate
applyCertificateChanges
Related REST API methods
POST /certificates/system/pkcs12
POST /certificates/system
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Installing a new self-signed certificate
Your system can generate and install a new self-signed SSL server certificate. The new certificate is good for five years.
- If the system is using a self-signed certificate, when you change the hostname name of the system, you need to generate a new SSL certificate.
- When you install the new certificate, if you are using encryption, you must repair the Vault service and then unseal the vault.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Click Update System Certificate.
Select the Self-Signed window.
Click Continue.
Your system generates a new self-signed server certificate.Click Accept.
Your system installs the new certificate.To continue using the Admin App, log out and then log back in.
Related CLI commands
generateSelfSignedCertificate
applyCertificateChanges
Related REST API methods
POST /certificates/system/selfsigned
POST /certificates/system
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Creating a CSR and installing the returned certificate
SSL server certificates are available from several trusted sources. To obtain a certificate created by a certificate authority (CA), you need to create a certificate signing request (CSR) and give it to the CA. The CA then generates the requested certificate and makes it available to you.
Creating a certificate signing request
You can create a CSR using the Admin App or a third-party tool. When you use the Admin App, the system securely stores the private key needed for installing the returned certificate, so you don’t need to save the key yourself.
Verify what information is required with the certificate authority (CA) that you plan to use.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Select the System tab.
Click Update System Certificate.
Select the CSR window.
Choose Generate a new certificate signing request and click Continue.
Fill in the following as needed:
- In the Common Name (CN) box, type the cluster name or an asterisk (*) followed by the DNS name of the system (for example, cluster.company.com or *.company.com).
Common Name (CN) is required.
- In the Organizational Unit (OU) box, type the name of the organizational unit that uses the system (for example, the name of a division or a name under which the company does business).
- In the Organization (O) box, type the full legal name of the organization.
- In the Location (L) box, type the name of the city in which the organization's headquarters are located.
- In the State/Province (ST) box, type the full name of the state or province in which the organization's headquarters are located.
- In the Country (C) box, type the two-letter ISO 3166-1 abbreviation for the country in which the organization's headquarters are located (for example,
USfor the United States). - In the Subject Alternate Name box, type
cluster.dns *.cluster.dns, where cluster is the name of your HCP for cloud scale cluster.For example: cluster.company.com *.cluster.company.com
Subject Alternative Name is required for Chrome browsers.
NoteThe System Management application supports a single SAN, so arrange with your CA to include two SANs in the final signed certificate.
- In the Common Name (CN) box, type the cluster name or an asterisk (*) followed by the DNS name of the system (for example, cluster.company.com or *.company.com).
Click Generate CSR.
The page displays the generated certificate request.Copy and paste the request text into a file and send that file to the CA.
Related CLI commands
generateCSR
Related REST API methods
PUT /certificates/system/csr
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Installing the certificates returned for a system-generated CSR
In response to a CSR, your CA gives you an SSL server certificate and any required intermediate certificates. These certificates are used in conjunction with the SSL server certificate to establish a certificate chain, an ordered list of certificates in which each certificate is trusted by the next. You need to upload and install these certificates on your system.
To preserve the chain of trust among the certificates, you need to upload the certificates in the correct order. That is, each certificate you upload must be immediately followed by the certificate that signs it. For information on the correct order for the certificate chain, see your CA.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Select the System tab.
Click Update System Certificate.
Select the CSR window.
Select the option I already generated a CSR and obtained a signed certificate and then click Continue.
Drag the certificate into the Upload certificate obtained from Certificate Authority box.
Click Accept.
Related CLI commands
uploadCSR
applyCertificateChanges
Related REST API methods
POST /certificates/system/csr
POST /certificates/system
You can get help on specific REST API methods for the Admin App at REST API - Admin.