Chapter 2. Authentication and Security


2.1. TLS/SSL Certification

The Red Hat Virtualization API requires Hypertext Transfer Protocol Secure (HTTPS) footnote:[See RFC 2818: HTTP Over TLS for secure interaction with client software, such as the SDK and CLI components. This involves obtaining the CA certificate used by the server and importing it into the certificate store of your client.

2.1.1. Obtaining the CA Certificate

You can obtain the CA certificate from the Red Hat Virtualization Manager and transfer it to the client machine using one of these methods:

Method 1

The preferred method for obtaining the CA certificate is to use the openssl s_client command line tool to perform a real TLS handshake with the server, and then extract the certificates that it presents.

  1. Run the openssl s_client command as in the following example:

    $ openssl s_client \
    -connect myengine.example.com:443 \
    -showcerts \
    < /dev/null

    Example output

    CONNECTED(00000003)
    depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
    verify error:num=19:self signed certificate in certificate chain
    ---
    Certificate chain
     0 s:/C=US/O=Example Inc./CN=myengine.example.com
       i:/C=US/O=Example Inc./CN=myengine.example.com.23416
    -----BEGIN CERTIFICATE-----
    MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
    FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
    SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
    -----END CERTIFICATE-----
     1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
       i:/C=US/O=Example Inc./CN=myengine.example.com.23416
    -----BEGIN CERTIFICATE-----
    MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
    FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
    Pkyg1rQHR6ebGQ==
    -----END CERTIFICATE-----

    The text between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines shows the certificates presented by the server.

    The first certificate is the certificate of the server itself. The second certificate is the certificate of the CA.

  2. Copy the CA certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, to the ca.crt file as in the following example:

    -----BEGIN CERTIFICATE-----
    MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
    FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
    Pkyg1rQHR6ebGQ==
    -----END CERTIFICATE-----
    Important

    This is the most reliable method to obtain the CA certificate used by the server. The rest of the methods described here will work in most cases, but they will not obtain the correct CA certificate if the certificate has been manually replaced by the server administrator.

Method 2

If you cannot use openssl s_client to obtain the certificate, you can use a command line tool, for example curl or wget, to download the CA certificate from the Red Hat Virtualization Manager. curl and wget are available on multiple platforms.

  • If using curl:

    $ curl \
    --output ca.crt \
    'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
  • If using wget:

    $ wget \
    --output-document ca.crt \
    'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
Method 3

Use a web browser to navigate to the certificate located at `https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA`.

Depending on the chosen browser, the certificate is downloaded or imported into the browser’s keystore:

  • If the browser downloads the certificate, save the file as ca.crt.
  • If the browser imports the certificate, export it using the browser’s certificate management options and save it as ca.crt.
Method 4

Log in to the Red Hat Virtualization Manager, export the certificate from the truststore, and copy it to your client machine.

  1. Log in to the Red Hat Virtualization Manager machine as root.
  2. Export the certificate from the truststore using the Java keytool management utility:

    # keytool \
    -keystore /etc/pki/ovirt-engine/.truststore \
    -storepass mypass \
    -exportcert \
    -alias cacert \
    -rfc \
    -file ca.crt

    This creates a certificate file called ca.crt.

  3. Copy the certificate to the client machine using the scp command:

    $ scp ca.crt myuser@myclient.example.com:/home/myuser/.

    Each of these methods results in a certificate file named ca.crt on your client machine. You must then import this file into the certificate store of the client.

2.1.2. Importing a Certificate to a Client

Importing a certificate to a client relies on how the client stores and interprets certificates. See your client documentation for more information on importing a certificate.

2.2. Authentication

Any user with a Red Hat Virtualization Manager account has access to the API. All requests must be authenticated using either OAuth or basic authentication, as described below.

2.2.1. OAuth Authentication

Since version 4.0 of Red Hat Virtualization the preferred authentication mechanism is OAuth 2.0, as described in RFC 6749.

OAuth is a sophisticated protocol, with several mechanisms for obtaining authorization and access tokens. For use with the Red Hat Virtualization API, the only supported one is the Resource Owner Password Credentials Grant, as described in RFC 6749.

You must first obtain a token, sending the user name and password to the Red Hat Virtualization Manager single sign-on service:

POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

The request body must contain the grant_type, scope, username, and password parameters:

Table 2.1. OAuth token request parameters
NameValue

grant_type

password

scope

ovirt-app-api

username

admin@internal

password

mypassword

These parameters must be URL-encoded. For example, the @ character in the user name needs to be encoded as %40. The resulting request body will be something like this:

grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
Important

The scope parameter is described as optional in the OAuth RFC, but when using it with the Red Hat Virtualization API it is mandatory, and its value must be ovirt-app-api.

If the user name and password are valid, the Red Hat Virtualization Manager single sign-on service will respond with a JSON document similar to this one:

{
  "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
  "token_type": "bearer",
  "scope": "...",
  ...
}

For API authentication purposes, the only relevant name/value pair is the access_token. Do not manipulate this in any way; use it exactly as provided by the SSO service.

Once the token has been obtained, it can be used to perform requests to the API by including it in the HTTP Authorization header, and using the Bearer scheme. For example, to get the list of virtual machines, send a request like this:

GET /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=

The token can be used multiple times, for multiple requests, but it will eventually expire. When it expires, the server will reject the request with the 401 HTTP response code:

HTTP/1.1 401 Unauthorized

When this happens, a new token is needed, as the Red Hat Virtualization Manager single sign-on service does not currently support refreshing tokens. A new token can be requested using the same method described above.

2.2.2. Basic Authentication

Important

Basic authentication is supported only for backwards compatibility; it is deprecated since version 4.0 of Red Hat Virtualization, and will be removed in the future.

Each request uses HTTP Basic Authentication [1] to encode the credentials. If a request does not include an appropriate Authorization header, the server sends a 401 Authorization Required response:

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. Encode an appropriate Red Hat Virtualization Manager domain and user in the supplied credentials with the username@domain:password convention.

The following table shows the process for encoding credentials in Base64.

Table 2.2. Encoding credentials for API access
ItemValue

User name

admin

Domain

internal

Password

mypassword

Unencoded credentials

admin@internal:mypassword

Base64 encoded credentials

YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

Provide the Base64-encoded credentials as shown:

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK
Important

Basic authentication involves potentially sensitive information, such as passwords, sent as plain text. The API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-level encryption of plain-text requests.

Important

Some Base64 libraries break the result into multiple lines and terminate each line with a newline character. This breaks the header and causes a faulty request. The Authorization header requires the encoded credentials on a single line within the header.

2.2.3. Authentication Sessions

The API also provides authentication session support. Send an initial request with authentication details, then send all subsequent requests using a session cookie to authenticate.

2.2.3.1. Requesting an Authenticated Session

  1. Send a request with the Authorization and Prefer: persistent-auth headers:

    HEAD /ovirt-engine/api HTTP/1.1
    Host: myengine.example.com
    Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
    Prefer: persistent-auth
    
    HTTP/1.1 200 OK
    ...

    This returns a response with the following header:

    Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure

    Take note of the JSESSIONID= value. In this example the value is 5dQja5ubr4yvI2MM2z+LZxrK.

  2. Send all subsequent requests with the Prefer: persistent-auth and Cookie headers with the JSESSIONID= value. The Authorization header is no longer needed when using an authenticated session.

    HEAD /ovirt-engine/api HTTP/1.1
    Host: myengine.example.com
    Prefer: persistent-auth
    Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
    
    HTTP/1.1 200 OK
    ...
  3. When the session is no longer required, perform a request to the sever without the Prefer: persistent-auth header.

    HEAD /ovirt-engine/api HTTP/1.1
    Host: myengine.example.com
    Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
    
    HTTP/1.1 200 OK
    ...
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.