Previous topic

Using Platform Services

Next topic

List Products

Odin Automation SDK
Last updated 16-Jan-2018

Using APS REST API

For external management systems getting access to the platform through the APS bus, the platform supports authentication and authorization via the OAuth Core 1.0 Revision A (hereafter OAuth-1.0a) protocol.

Set up HTTPS Access to Platform

The OAuth authentication scheme requires access to the platform only through the HTTPS protocol. If your platform is in production, it must be already available through HTTPS. If you have an APS Sandbox, then probably you have not configured it to use the secure HTTPS protocol yet.

To use HTTPS, you should configure a brand access point as follows (not for a production system):

  1. In the provider control panel, navigate to Infrastructure > Service Nodes, and make sure the management node, for example, a.isv1.apsdemo.org, is in the Ready to provide state.
  2. Navigate to System > Settings and click Brands on the screen.
  3. Click Add New Brand and in the Domain field enter the domain name of the management node, that is the same domain name you see in the browser address string, for example, “a.isv1.apsdemo.org”.
  4. Click Next and then on the next screen click Finish.

Set up User’s Credentials

The OAuth-1.0a protocol requires a sender to have a trusted pair of consumer key and secret. You can generate that pair for a user whose credentials an external system will use to manage resources in the platform.

  1. In the provider control panel, create a special staff member whose OAuth credentials the external management system will use.

  2. For the new staff member, generate the OAuth credentials:

    • In the provider control panel, open the details of the newly created staff member.

    • On the APS Bus Access tab, click Create to generate the Consumer Key and Consumer Secret.

      Warning

      The consumer secret is visible only once. After you leave the screen, the consumer secret will not be visible anymore. So, it makes sense to save it immediately.

  3. In the Allowed Operations section, add a separate entry for a group of allowed operations exposed by a certain APS type. Each entry consists of two parts:

    • ID of the APS type that exposes the allowed operations.
    • An HTTP method (the verb in operation declaration), either GET, POST, PUT, or DELETE.

    In the following example, it is allowed to operate accounts by means of GET and POST requests:

    ../../_images/allowed-operations.png

    Note

    In the APS Type field, omit the APS type version.

Choose REST Client

Requirements

To use OAuth-1.0a supported by the platform, choose a REST client that meets the following requirements.

  • The client must be able to construct the Authorization header compliant with the OAuth-1a protocol.

    It means the client must accept the two parameters that the platform generates - consumer key and consumer secret - and then construct the other required OAuth parameters in the header as in the following example:

    Authorization: OAuth
    oauth_consumer_key="LFkJjlAjluEfL57dRxNnsi6WWMDduxEl",
    oauth_signature_method="HMAC-SHA1",
    oauth_timestamp="1508234992",
    oauth_nonce="kUO2sQ",
    oauth_version="1.0",
    oauth_signature="nYuf8bT3rOOMaMJR9ZosPKoNupo%3D"
    
  • The client must be able to send REST requests through the HTTPS protocol and accept self-signed SSL certificates when testing some operations on a test platform.

  • The client must not encode special symbols used in Resource Query Language (RQL). For example, some REST clients replace parenthesis ‘(‘ and ‘)’ respectively for ‘%28’ and ‘%29’, which is not acceptable for the RQL parser.

Sample Script

If your management system uses some scripts or binary executables based on a programming language, the best way is to find out a library or modules that support the OAuth-1.0a protocol in that language.

A simple Python script may look as follows:

from requests_oauthlib import OAuth1Session

# Enter input parameters:
consumer_key = 'ug7nnV3aq4VwGQQzyiFRDSGwa7QZY0YE'
consumer_secret = 'cccMHKhIIVupWAEWtYeQmg9DVe0DSP...'
url = 'https://a.isv1.apsdemo.org/aps/2/resources'

# Set session parameters and get response:
session = OAuth1Session(consumer_key, consumer_secret)
response = session.get(url, verify=False)
print response.text

The script requires the requests_oauthlib module that you can install through the Python package manager:

$ sudo pip install requests_oauthlib

This is a quick demo illustrating generic and custom REST operations on the platform:

Sample GUI Client

You can also find out a GUI tool that meets the above requirements. A GUI client helps you test some key operations before implementing them in a management system.

For example, the Insomnia REST client meets all the above requirements. Its preferences and request settings allow you to disable validation of SSL certificates and disable URL encoding.

../../_images/insomnia-preferences.png ../../_images/insomnia-settings.png

The OAuth 1.0 configuration section allows you to select the HMAC-SHA1 signature method, enter a consumer key, consumer secret, and the OAuth protocol version in order to construct all other fields for the Authorization header.

../../_images/insomnia-example.png

SSL Hints

When using HTTPS in your browser and REST client, you may meet with the following cases when your action is rejected:

  • The REST client does not accept a self-signed certificate from your test platform.
    • If you use a REST client as a plugin in your browser, first get access to the platform from your browser using HTTPS and accept the SSL certificate. Then switch back to your REST client. Now it must accept the SSL certificate.
    • If your REST client is a separate application, turn off the SSL certificate verification in the application settings.
  • If you have reinstalled your test platform under the same domain name and you cannot log in to the platform control panel through your browser or REST client the most probable cause is the cookies stored in the browser or REST client from the previous installation. For example, you continuously get a message similar to “Your session has expired…”. Clear the old cookies received from the server and try again.

Hints for Testing with User Token

When testing some REST operations on the APS bus, you can find it easier and quicker to use a temporary security token of a user to authenticate your requests. This method allows managing resources on all levels - provider, reseller, customer, and service user. This depends on the security role of the user whose token you use.

To generate a user token on your test platform, follow these steps:

  1. Log in to the provider control panel (PCP).
  2. Ensure the platform is in the Development mode. To check this:
    • Navigate to System > Settings and click System Properties.
    • Verify if the APS development mode is Enabled. Otherwise, click the Edit button on the bottom of the screen and switch the system to this mode.
  3. Navigate to System > Settings and in the Integration section click User APS tokens. You will see a list of users. The highest permissions are assigned to admin. Use the admin’s token if your solution requires the highest permissions.
  4. Click on the selected user and save the current token displayed on the screen.

Note

A user token is valid only for a short period of time, depending on the platform version - from 5 to 30 minutes. On its expiration, you have to update the token.

To authenticate a request via the user token, you must add the APS-Token header whose value must be the newly generated user token.