Getting Started
Vdisk Devgrps
Auth
Alerts Notifylists
Cloud Profiles
Cloud Unit
Data Movement Policy
Data Movement
Data Movement Stats Files
Data Movement Stats Mtrees
Data Movement Stats Recall
Managed Files
Licenses
Mdtags
Mtrees
Mtrees Id Rlfiles
Mtrees Id Stats
Mtrees Id Stats Capacity
Mtree Id Stats Compressions
Networks
Network
Network Nic
Cifs Shares
Ddboost
Ddboost Clients
Ddboost Storage Units
Ddboost Users
Nfs Exports
Nfs Exports Id Clients
Nfs Exports Id Referrals
Alerts
Vdisk Devices
Vdisk Pools
Vdisk Stimgs
Services
Services Asup
Services License Server
Services Log
Mdtags Services
Services Ntp
Snmp
Settings
Tenant Units
Tenants
Stats
Stats Capacity
Comp Measurements Support Check
Comp Measurements
Stats File Replications
Filesys Stats
Stats Performances Mtrees
Stats Systems File Replications
Support Bundles
System
System Repl
System Space
Users
Sso Registration
Trust

Authentication and authorization

In this tutorial, you can learn about authentication and authorization using REST API in the PowerProtect DD system.

Authentication

For a client to use PowerProtect DD system REST API, the client must first authenticate the user through the RESTful server on the PowerProtect DD system. The RESTful server also performs RBAC (Role Base Access Control) to authorize the user based on user role in the system. Client authentication can be performed in the following two ways:

Using username and password

The client must send an authentication request with the required username and password. Valid users can be authorized by the RESTful server on the PowerProtect DD system by providing an authentication token in the HTTP response header.

curl --request POST \
     --url https://<DD-SYSTEM-IP/FQDN>:3009/rest/v1.0/auth \
     --data '{"username":"<your-user-name>","password":"<your-password>"}'

Sample response:

< HTTP/1.1 201 Created
< Content-Type: application/json
< Content-Length: 92
< X-DD-AUTH-TOKEN: 94fe05ac0f4c8c5cb75cb53632c5d9a40
< X-DD-UUID: 68c8142e619b8d9d:fee7d1c14eda2780
< Access-Control-Allow-Credentials: true
< Cache-Control: no-cache
* Server Data Domain OS is not blacklisted
< Server: Data Domain OS
< Access-Control-Expose-Headers: AUTHORIZATION, X-DD-AUTH-TOKEN, X-DD-JSON-RESPONSE-WITH-ROOT, X-DD-PEER-USERNAME
<
{"details": "success", "code": 0, "link": [{"rel": "related", "href": "/rest/v1.0/system"}]}

The subsequent API calls must include X-DD-AUTH-TOKEN in the HTTP request header. The default session timeout is 30 minutes.

--header 'X-DD-AUTH-TOKEN: <your-auth-token>'

Certificate-based authentication

The authentication and authorization process is the PowerProtect DD in-house client certification verification process through the PowerProtect DD REST API. This process runs on top of the SSL layer. The normal SSL handshake and verification through HTTPS between client and server must complete before the authentication and authorization process begins. The client certificate mechanism uses a strong public key infrastructure and a symmetric cryptography. The mechanism provides a secure way to access PowerProtect DD systems. The client certificate must contain the user information (user-name). This user must be a valid, local Network Information Service (NIS) or Active Directory (AD) user on the server side (that is, on the Data Domain Management Center or standard Data Domain system). The following sections provide procedures for preparing client and server for certificate-based authentication.

Prepare the client

You can prepare the client side certificate-based authentication (CA) in the following way:

  1. Obtain the CA certificate and the client certificate. The client must obtain the CA certificate and the client certificate with a valid local or name service (NIS or AD) username on the PowerProtect DD system.
  2. Import the CA certificate on the PowerProtect DD system. For example:
ssh sysadmin@<DD-SYSTEM-IP/FQDN> adminaccess certificate import ca application login-auth < cacert.pem
  1. Copy the PowerProtect DD system CA certificate to the client system. If required, you can copy the PowerProtect DD system CA certificate and save it on the local system so the system can verify the server communication. You can use OpenSSL to get the public CA of the PowerProtect DD system. For example:
openssl s_client -showcerts -connect <DD-SYSTEM-IP/FQDN>:3009  < /dev/null

The following sample output shows a case in which the last server certificate is the CA certificate. You can copy the CA certificate from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE---- to use as needed.

Note: On a LINUX or UNIX system for system wide use, OpenSSL keeps the trusted CA certificates in /etc/ssl/certs.

$ openssl s_client -showcerts -connect 10.25.183.157:3009 < /dev/null CONNECTED(00000003)depth=1 /C=US/ST=CA/L=Santa Clara/O=Valued Datadomain Customer/OU=RootCA/CN=ddve-25183157.brs.lab.emc.comverify error:num=19:self signed certificate in certificate chain verify return:0 ---Certificate chain0 s:/C=US/ST=CA/OU=Host Certificate/O=Valued DataDomain customer/CN=ddve-25183157.brs.lab.emc.comi:/C=US/ST=CA/L=Santa Clara/O=Valued Datadomain Customer/OU=Root CA/CN=ddve-25183157.brs.lab.emc.com -----BEGIN CERTIFICATE-----MIICgjCCAesCAQIwDQYJKoZIhvcNAQEFBQAwgY8xCzAJBgNVBAYTAlVTMQswCQYD VQQIDAJDQTEUMBIGA1UEBwwLU2FudGEgQ2xhcmExIzAhBgNVBAoMGlZhbHVlZCBE YXRhZG9tYWluIEN1c3RvbWVyMRAwDgYDVQQLDAdSb290IENBMSYwJAYDVQQDDB1k ZHZlLTI1MTgzMTU3LmJycy5sYWIuZW1jLmNvbTAeFw0xNDEyMTcxNzAwMDhaFw00 NTEyMTAwMTAwMDhaMIGCMQswCQYDVQQGEwJVUzELMAkGA1UECAwCQ0ExGTAXBgNV BAsMEEhvc3QgQ2VydGlmaWNhdGUxIzAhBgNVBAoMGlZhbHVlZCBEYXRhRG9tYWlu IGN1c3RvbWVyMSYwJAYDVQQDDB1kZHZlLTI1MTgzMTU3LmJycy5sYWIuZW1jLmNv bTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEApjSl3E0R2gGy0pxsvdHkQLEE fKuup2bE3HT8t2QokJYAadw/jb4BaHZ3sKkR+nr5ZKj4QfHea15U6+uDaGF6iT/1 5g6pPj+Jh4Cnyn9iIjFJNPvQJXsk5A//JLh5Fr6lIQVizqJ9vOr88QvJsDPqVeJ4 ndE92XdxXOMDwMFPvlECAwEAATANBgkqhkiG9w0BAQUFAAOBgQAOY2DRbw9xBD/M irnP4L8+T1dtk9i6ZMPP9rehlqzxo0TRhy/XfaX/wlhPNnymwAGT0m9U1Oib6AVk /RuZM0WNnGzarRlk0KYStD84MOfGsPRbPNkPfk/tBNxxkCnMjdawdv9xyt6Flqin /N0FUcNkL1qm5Y8JwSajx6AilXGt4w==-----END CERTIFICATE-----1 s:/C=US/ST=CA/L=Santa Clara/O=Valued Datadomain Customer/OU=Root CA/CN=ddve-25183157.brs.lab.emc.com i:/C=US/ST=CA/L=Santa Clara/O=Valued Datadomain Customer/OU=Root CA/CN=ddve-25183157.brs.lab.emc.com-----BEGIN CERTIFICATE-----MIIClDCCAf2gAwIBAgIBADANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMCVVMx CzAJBgNVBAgMAkNBMRQwEgYDVQQHDAtTYW50YSBDbGFyYTEjMCEGA1UECgwaVmFs dWVkIERhdGFkb21haW4gQ3VzdG9tZXIxEDAOBgNVBAsMB1Jvb3QgQ0ExJjAkBgNV BAMMHWRkdmUtMjUxODMxNTcuYnJzLmxhYi5lbWMuY29tMB4XDTE0MTIxODAxMDAw OFoXDTQ1MTIxMDAxMDAwOFowgY8xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTEU MBIGA1UEBwwLU2FudGEgQ2xhcmExIzAhBgNVBAoMGlZhbHVlZCBEYXRhZG9tYWlu IEN1c3RvbWVyMRAwDgYDVQQLDAdSb290IENBMSYwJAYDVQQDDB1kZHZlLTI1MTgz 
MTU3LmJycy5sYWIuZW1jLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA wKoti2sp12Yj3H3PfUui3Mxv3H64M8N4B8RPAgg3aeAK/EcdnK1SnqtIfoyAytc0 MG6uqVKY0A/GATp4TaxFATRnrlfdbbOk41eHvgkyaSO1IYMU0APpdGzQX+4sSbtH aEJhseEEDa3F35qACk3TSzLYTJAbn+6D1RhgP6R5jn8CAwEAATANBgkqhkiG9w0B AQUFAAOBgQCihdO8qfAThy1/0R3btmNYrNkhHobUA41bNr+Ca7aGVgNomO+sugcs t8B5fN+UKFFTEjz4e4vOkA7RbIVG2+6MxJjmZEaWjgvBkpMWrikqxwAnJZPqX/WX etec6lhTRjgoCURwK+OMyJypRrx7uOlxOiSgSrjjDLgVv2ZJ1+lO0Q==-----END CERTIFICATE--------Server certificatesubject=/C=US/ST=CA/OU=Host Certificate/O=Valued DataDomaincustomer/CN=ddve-25183157.brs.lab.emc.comissuer=/C=US/ST=CA/L=Santa Clara/O=Valued Datadomain Customer/OU=RootCA/CN=ddve-25183157.brs.lab.emc.com 
  1. Import the client certificate to the browser. To use the client certificate from a browser, you must import the client certificate to the browser so the browser can display the certificate before sending the request to the PowerProtect DD system. The client must provide proof of possession to the browser by providing both private and public keys. The browser validates the client using private and public keys, but only sends the client public key to the DD system.

Importing the CA certificate to Chromium on Ubuntu 12.04

To import a client certificate ona Chromium browser (Ubuntu 12.04):

  1. Open a Chromium browser instance.
  2. Click Edit->Preferences.
  3. Navigate to HTTPS/SSL(Manage Certificates…).
  4. Select the Your Certificates tab and click Import.
  5. Go to your client certificate directory and choose the p12 certificate file. When prompted, specify a password to decrypt the PKCS12 file.

Importing a client certificate to Safari and Chromium on a MacBook Pro Computer

  1. In the EMC_CA/certs directory, double-click the p12 certificate and follow the instructions for importing the client certificate on the MacBook.

  2. Open Keychain Access and mark the client certificate as Trust:

    1. Open Keychain Access.
    2. Select System in the top left panel and select the category My Certificates in the bottom left panel.
    3. Right-click the certificate.
    4. Select Get Info.
    5. Click Trust.
    6. From the When using this certificate area, select Always Trust.
  3. Enable applications to access this certificate without requiring a password:

    1. From /Applications/Utilities, open Keychain Access.
    2. From the Keychain pane, select the System keychain.
    3. Select System in the top left panel, and select the category My Certificates in the bottom left panel.
    4. Click the arrow next to the imported certificate.
    5. Double-click the private key.
    6. From the Access Control tab, select Allow all applications to access this item.
    7. Click Save Changes and authenticate as a local administrator when prompted.

Prepare the server

To prepare the server for certificate-based authentication on a PowerProtect DD system:

  1. Verify that the client certificate is properly installed on the PowerProtect DD system. For example,
adminaccess certificate show imported-ca application login-auth
  1. Ensure that the username is valid on the PowerProtect DD system.

If the user is an NIS user, complete the following steps on the target PowerProtect DD system:

  1. Identify group information for the NIS user by running the following Unix/Linux shell command to query name services for the user group information. For example:
#id anjala
uid=200(anjala) gid=200(anjala) groups=200(anjala)
  1. Provide the RBAC role for the user NIS group.
# authentication nis groups add anjala role admin
  1. If there is no default value available from DHCP, ensure that the NIS server and domain information are set with the following CLI commands:
authentication nisserver add <server-list>
authentication nis domain set <domain>
  1. Enable NIS in the following way:
# authentication nis enable
# authentication nis show 
		NIS Summary: 
		Domain: datadomain.com 
		Servers: 10.25.209.6,10.25.232.17 
		Admin Groups: anjala 
		User Groups: 
		Backup Operator Groups: 
		Enabled: Yes 
		Status: Good
  1. If the user is a local user, check the user status in the following way:
# user show list
  1. If the user does not exist, add the user with the desired role by using the following command:
# user add <username> role [admin|user...]

After the server and the client are ready, try the following command to perform the certificate-based authentication:

curl --tlsv1 --cacert <path-to-dd-ca-cert>/<dd-cacert> \
     --request GET \
     --header "Content-Type: application/json" \
     --url https://<DD hostname>:3009/rest/v1.0/system \
     --cert <path-to-client-cert>/<client-public-cert> \
     --key <path-to-client-cert>/<client-private-key>

If you do not want to specify PowerProtect DD system public CA certificate, use –k option :

curl --tlsv1 --request GET \
     --header "Content-Type: application/json" \
     --url https://<DD hostname>:3009/rest/v1.0/system \
     --cert <path-to-client-cert>/<client-public-cert> \
     --key <path-to-client-cert>/<client-private-key> -k

Note:

  • The PowerProtect DD hostname is the same as the common name in the host certificate of PowerProtect DD system because (for security purposes) the peer name must match the subject name in the PowerProtect DD host certificate.
  • The PowerProtect DD hostname must be resolvable.

Security Officer

PowerProtect DD appliances traditionally have a security officer role, and administrative operations require a sign-off from the security officer. In PowerProtect DD REST API, a new HTTP header X-DD-SEC-OFFICER is defined to support passing the security officer credential. The HTTP header for security officer can be mandatory or optional. It depends on the definition of the REST API resource or method such as POST or PUT.

There are two types of security officer enforcement information:

  1. JWT:
X-DD-SEC-OFFICER: JWT <jwt token which contains security officer information>
  1. USER:
X-DD-SEC-OFFICER: USER <base64 encode of json string of username and password>. 

An example of type USER:

X-DD-SEC-OFFICER: USER base64_encoded("{"username":"security_officer", "password":"abc123" }")

X-DD-SEC-OFFICER: USER eyAidXNlcm5hbWUiOiJzZWN1cml0eV9vZmZpY2VyIiwgInBhc3N3b3JkIjoiYWJjMTIzIiB9

Note: Type JWT is for JSON Web Token access enforcement, which is defined for future use.