Chapter 3. Authenticating API Calls
Interaction with the Satellite API requires SSL authentication with Satellite Server CA certificate and authentication with valid Satellite user credentials. This chapter outlines the authenticating methods you can use.
3.1. SSL Authentication Overview
Red Hat Satellite uses HTTPS, which provides a degree of encryption and identity verification when communicating with a Red Hat Satellite Server. Satellite 6.12 does not support non-SSL communications.
Each Red Hat Satellite Server uses a self-signed certificate. This certificate acts as both the server certificate to verify the encryption key and the certificate authority (CA) to trust the identity of Satellite Server.
3.1.1. Configuring SSL Authentication
Use the following procedure to configure an SSL authentication for the API requests to Satellite Server.
Procedure
Obtain a certificate from the Satellite Server with which you want to communicate using one of the following options:
If you execute the command from a remote server, obtain a certificate using SSH:
$ scp root@satellite.example.com:/var/www/html/pub/katello-server-ca.crt /etc/pki/ca-trust/source/anchors/satellite.example.com-katello-server-ca.crt
If you execute the command directly on the Satellite Server, copy the certificate to the
/etc/pki/ca-trust/source/anchors
directory:$ cp /var/www/html/pub/katello-server-ca.crt /etc/pki/ca-trust/source/anchors/satellite.example.com-katello-server-ca.crt
Add the certificate to the list of trusted CAs:
update-ca-trust extract
Verification
Verify that the certificate is present in the NSS database by entering the API request without the
--cacert
option:$ curl --request GET \ --user sat_username:sat_password \ https://satellite.example.com/api/v2/hosts
3.2. HTTP Authentication Overview
All requests to the Satellite API require a valid Satellite user name and password. The API uses HTTP Basic Authentication to encode these credentials and add to the Authorization
header. For more information about Basic Authentication, see RFC 2617 HTTP Authentication: Basic and Digest Access Authentication. If a request does not include an appropriate Authorization
header, the API returns a 401 Authorization Required
error
Basic authentication involves potentially sensitive information, for example, it sends passwords as plain text. The REST API requires HTTPS for transport level encryption of plain text requests.
Some base64 libraries break encoded credentials into multiple lines and terminate each line with a newline character. This invalidates the header and causes a faulty request. The Authorization header requires that the encoded credentials be on a single line within the header.
3.3. Personal Access Token Authentication Overview
Red Hat Satellite supports Personal Access Tokens that you can use to authenticate API requests instead of using your password. You can set an expiration date for your Personal Access Token and you can revoke it if you decide it should expire before the expiration date.
3.3.1. Creating a Personal Access Token
Use this procedure to create a Personal Access Token.
Procedure
- In the Satellite web UI, navigate to Administer > Users.
- Select a user for which you want to create a Personal Access Token.
- On the Personal Access Tokens tab, click Add Personal Access Token.
- Enter a Name for you Personal Access Token.
- Optional: Select the Expires date to set an expiration date. If you do not set an expiration date, your Personal Access Token will never expire unless revoked.
Click Submit. You now have the Personal Access Token available to you on the Personal Access Tokens tab.
ImportantEnsure to store your Personal Access Token as you will not be able to access it again after you leave the page or create a new Personal Access Token. You can click Copy to clipboard to copy your Personal Access Token.
Verification
Make an API request to your Satellite Server and authenticate with your Personal Access Token:
# curl https://satellite.example.com/api/status --user My_Username:My_Personal_Access_Token
You should receive a response with status
200
, for example:{"satellite_version":"6.12.0","result":"ok","status":200,"version":"3.5.1.10","api_version":2}
If you go back to Personal Access Tokens tab, you can see the updated Last Used time next to your Personal Access Token.
3.3.2. Revoking a Personal Access Token
Use this procedure to revoke a Personal Access Token before its expiration date.
Procedure
- In the Satellite web UI, navigate to Administer > Users.
- Select a user for which you want to revoke the Personal Access Token.
- On the Personal Access Tokens tab, locate the Personal Access Token you want to revoke.
- Click Revoke in the Actions column next to the Personal Access Token you want to revoke.
Verification
Make an API request to your Satellite Server and try to authenticate with the revoked Personal Access Token:
# curl https://satellite.example.com/api/status --user My_Username:My_Personal_Access_Token
You receive the following error message:
{ "error": {"message":"Unable to authenticate user My_Username"} }
3.4. OAuth Authentication Overview
As an alternative to basic authentication, you can use limited OAuth 1.0 authentication. This is sometimes referred to as 1-legged OAuth in version 1.0a of the protocol.
To view OAuth settings, in the Satellite web UI, navigate to Administer > Settings > Authentication. The OAuth consumer key is the token to be used by all OAuth clients.
Satellite stores OAuth settings in the /etc/foreman/settings.yaml
file. Use the satellite-installer
script to configure these settings, because Satellite overwrites any manual changes to this file when upgrading.
3.4.1. Configuring OAuth
To change the OAuth settings, enter the satellite-installer
with the required options. Enter the following command to list all the OAuth related installer options:
# satellite-installer --full-help | grep oauth
Enabling OAuth mapping
By default, Satellite authorizes all OAuth API requests as the built-in anonymous API administrator account. Therefore, API responses include all Satellite data. However, you can also specify the Foreman user that makes the request and restrict access to data to that user.
To enable OAuth user mapping, enter the following command:
# satellite-installer --foreman-oauth-map-users true
Satellite does not sign the header in an OAuth request. Anyone with a valid consumer key can impersonate any Foreman user.
3.4.2. OAuth Request Format
Every OAuth API request requires the FOREMAN-USER
header with the login of an existing Foreman user and the Authorization
header in the following format:
--header 'FOREMAN-USER: sat_username' \ --header 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="secretkey",oauth_signature_method="hmac-sha1",oauth_timestamp=timestamp,oauth_signature=signature'
Use an OAuth client library to construct all OAuth parameters. For an example that uses the requests_oauthlib Python module, see How to execute an API call using the OAuth authentication method via python script in Red Hat Satellite 6? in the Red Hat Knowledgebase.
Example
This example lists architectures using OAuth for authentication. The request uses a sat_username username in the FOREMAN-USER
header. With the --foreman-oauth-map-users
set to true
, the response includes only architectures that the user has access to view. The signature reflects every parameter, HTTP method, and URI change.
Example request:
$ curl 'https://satellite.example.com/api/architectures' \ --header 'Content-Type: application/json' \ --header 'Accept:application/json' \ --header 'FOREMAN-USER: sat_username' \ --header 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="secretkey",oauth_signature_method="hmac-sha1",oauth_timestamp=1321473112,oauth_signature=Il8hR8/ogj/XVuOqMPB9qNjSy6E='
Additional resources