White Papers

7 REST API Guide  OpenManage Essentials | Revision A02
1.3 Security
The REST services will be exposed only through HTTPS to ensure that the common threats associated with
HTTP traffic are mitigated. Administrator will have the option of updating the SSL self-signed certificate with a
customer-provided certificate (for example, by uploading a PKCS-12 certificate or by signing an application-
generated CSR request).
1.4 Authentication mechanisms
There are several common schemes for enabling authentication of REST requests. The following is a
summary of the most common schemes:
Basic authentication
The authorization header in the request has the base-64 encoding of the credentials (username and
password). If the credentials are not provided, a 401 (Authorization Failure) error is returned. Since the
encoding is weak, this mechanism is only supported when SSL/TLS is used for the transport.
Digest authentication
The authorization header in the request has a digest computed from the user credentials. The server verifies
if the digest matches a digest it computes. This is more secure than basic authentication since the credentials
are not encoded over the wire.
Two-legged OAuth-based authentication
The 2-legged OAuth mechanism is popular in many public REST APIs in the industry. For an architectural
overview, see 2-legged OAuth with OAuth 1.0 and 2.0. In summary, the client makes a request for a token
from the server by supplying its credentials. Depending on the type of access token (for example, Client
Credentials type), the client constructs an authorization header in subsequent requests. Therefore, the
credentials do not need to be sent for every request after the initial grant of the access token.
1.5 Resource addressing
Each resource that is managed needs to be uniquely addressable using a distinct URI. The URI syntax needs
to be intuitive and indicative of any associative relationship with a parent resource.
There are several acceptable ways to address specific resources either as instances of specific resource
classes or within an associated parent context.
1) Pattern: <BASE_URI>/<resource class identifier>/<resource instance identifier>
Example: <BASE_URI>/Devices/1234 (where, 1234 is the unique identifier for the device)
2) Pattern: <BASE_URI>/<parent resource identifier>/<resource class identifier>
Example: <BASE_URI>/DeviceGroups/5/Devices/1234/Firmware
(To retrieve all the firmware resources for a specific device)