Getting started with RHSM APIs in tech preview

Updated -

Using RHSM APIs in the tech preview

We are currently looking for feedback on the implementation of our new API offerings. At the end of this document, there are links for support and feedback. Please let us know if you need anything or have any requests!

Using APIs in RHSM can help you more effectively keep track of and automate how you manage your Red Hat subscriptions and entitlement usage. By using APIs in RHSM, you can:

  • Control which tooling you use for which products
  • Better manage your system inventory
  • Update and secure your systems more efficiently
  • Continue receiving official support for your Red Hat products

In order to transition to using APIs for Red Hat Subscription Management, Red Hat has created a tech preview program for early access and feedback. Red Hat is in the process of decommissioning Red Hat Network (RHN), including access to its APIs. As a part of this effort, Red Hat has been developing and documenting support for RHSM.

Prerequisites

Red Hat Subscription Management APIs use OAuth 2.0 for authorization. To obtain a token and access the APIs, you will need the following pieces of information:

  • Client ID and Secret provided by Red Hat
  • Your Customer Portal credentials
  • Grant Type = Password
  • Token URL = https://sso.redhat.com/auth/realms/3scale/protocol/openid-connect/token

Obtaining your Client ID and secret

To create a new Client ID and secret, called an application, or view your existing RHSM API applications for your organization, visit the RHSM API keys page.

Only one RHSM API application is necessary for each organization, although some customers may choose to create multiple keys to hand out to application developers so that an individual key can be suspended without interrupting other developers.

Generating a new offline token

If you need a permanent (“offline”) token for the sake of security (e.g., not storing Customer Portal credentials in plaintext). An offline token never expires and can be used to access RHSM API functionality, as well. It effectively works as a password and allows you to continue being able to authenticate your account without having to create new refresh tokens.

Warning: Please use password management that is consistent with networking best practices. It is never safe to store any passwords or credentials in plaintext. Treat your offline token with the same security measures that you would a password to protect it against unauthorized use.

To generate an offline token:


** It is never safe to store any passwords or credentials in plaintext. Treat your offline token with the same security measures that you would a password to protect it against unauthorized use. ** Set customer portal credentials and client ID and client secret (in this example we set it in plaintext): # rhn_user='username' rhn_password='password' client_id='854dgdwe65' client_secret='6d24gfdg55954542g4fgfg428' Some function to easily grab the token: # function jsonValue() { KEY=$1 num=$2 awk -F"[,:}]" '{for(i=1;i<=NF;i++){if($i~/'$KEY'\042/){print $(i+1)}}}' | tr -d '"' | sed -n ${num}p } Generate the token: # token=`curl https://sso.redhat.com/auth/realms/3scale/protocol/openid-connect/token -d "grant_type=password&username=$rhn_user&password=$rhn_password&client_id=$client_id&client_secret=$client_secret&scope=offline_access" | jsonValue access_token`

Generating a new refresh token

Refresh tokens are used to request new access tokens, which you need to use RHSM APIs. Refresh tokens normally expire one hour after initial authentication, at which point you must create a new refresh toke. Refresh token authentication lasts an hour and is a good solution for security concerns regarding storing a more permanent token.

Once you have created the refresh token, RHSM also includes a new access token that is valid for five minutes. New access tokens are temporary tokens that can be used for testing and validation.

Warning: Please use password management that is consistent with networking best practices. It is never safe to store any passwords or credentials in plaintext.

# rhn_user='username' rhn_password='password' client_id='854dgdwe65' client_secret='6d24gfdg55954542g4fgfg428'

# function jsonValue() {
KEY=$1                                            
num=$2
awk -F"[,:}]" '{for(i=1;i<=NF;i++){if($i~/'$KEY'\042/){print $(i+1)}}}' | tr -d '"' | sed -n ${num}p
}

# refresh_token=`curl https://sso.redhat.com/auth/realms/3scale/protocol/openid-connect/token -d "grant_type=password&username=$rhn_user&password=$rhn_password&client_id=$client_id&client_secret=$client_secret&scope=offline_access" | jsonValue refresh_token`

# curl https://sso.redhat.com/auth/realms/3scale/protocol/openid-connect/token -d "grant_type=refresh_token&refresh_token=$refresh_token&client_id=$client_id&client_secret=$client_secret" 

You should see an output similar to the below where TOKENOUTPUT is the actual access and refresh tokens you will use:

{
  "access_token": "TOKENOUTPUT”,
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "TOKENOUTPUT",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "65ffffff-52ff-46ff-82ff-887c842fffff"

The access_token is what needs to be set/used as authorization token to perform the API call.

# token=`curl https://sso.redhat.com/auth/realms/3scale/protocol/openid-connect/token -d "grant_type=refresh_token&refresh_token=$refresh_token&client_id=$client_id&client_secret=$client_secret" | jsonValue access_token`

Perform an API call with the token

Example API call to list 100 systems:

# curl -H "Authorization: Bearer $token"  "https://api.access.redhat.com/management/v1/systems?limit=100"

Optional CLI tooling support

Install a JSON formatting tool, such as jq or json_reformat to receive more structured returns of your API calls.

  • jq is a command-line JSON processor which can be installed using the yum command: sudo yum install jq
  • json_reformat is a command-line JSON formatter that comes standard on Red Hat Enterprise Linux.

Developers familiar with standard OIDC libraries that supports OAuth 2.0 can use those libraries to build authorization to the Red Hat Subscription Management APIs into scripts and applications.

An option for testing APIs, or for users who access APIs less frequently, is to use a REST client. As long as your REST client supports OAuth 2.0 or custom form submission, you can use that client to access the Red Hat Subscription Management APIs. Some examples of popular REST clients include Postman, Advanced REST Client, and Restlet.

While RHSM no longer officially supports the took application, you can still use it if you found it to be a helpful solution to your workflow.

Accessing available Red Hat Subscription Management APIs

Red Hat provides a Swagger file to describe the specifications of the Red Hat Subscription Management APIs. The Swagger specification includes information about the API endpoints available, input parameters, expected output, and possible error responses. The swagger file can be imported into REST clients like Postman or RESTlet to automatically build a library of API calls. The RHSM API Swagger documentation can be found on the RHSM API Swagger page linked at the bottom of this article.

Contact Red Hat

If you run into problems and require support, please open a support case.

We would love feedback on the API implementation we have so far. If you have any suggestions, please feel free to let us know in our survey.

Resources for downloads and Swagger documentation

9 Comments

The API only appears to support GET requests at this point, is that correct? Are there plans to allow changes via the API?

Hi Erinn! Yes, throughout the Tech Preview, we will be publishing additional endpoints for actions like attaching or removing entitlements from Systems, creating and managing Subscriptions on Subscription Allocations and Activation Keys, and many of the other functions you are accustomed to.

using python request module , it seems it is only returning response in html. Do you have example of what the request should look like ? This is what I have . r = requests.get(url, headers={"Content-Type": "application/json","Authorization":"Bearer %s " %(auth_token) })

Hi Mahesh.

The request should return JSON not the HTML. Try to load the json as below and check if you get any error.

json.loads(r.text)

Hello, When I request a list of systems by using the api, the list is limited to 100 even if I use the "?limit=500" parameter, did somebody notice the same ( or the syntax is not correct in the Swagger ) ? Exemple : curl -s -H "Authorization: Bearer $BEARER" -H "Content-Type: application/json" -X GET https://api.access.redhat.com/management/v1/systems?limit=500

The syntax is correct, though the description states, "The default and max number of results in a response are 100." We are always looking to tune the performance of these calls and may increase the max in the future.

Ok, Thanks.

We can obtain some information for a system ( Errata, Package, available pool ) but not the subscribed entitlement name, do you think it will be possible in the future ?

Regards,

Seeing -- {"error":"not_allowed","error_description":"Offline tokens not allowed for the user or client"}%

Getting the same error