OAuth 1 Authorization

The OAuth-1.0a protocol requires a sender to have a trusted consumer key and secret pair.

Set Up the User’s Credentials

You must generate the required secret pair for a user whose credentials an external system will use to manage resources on 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

     Save the consumer secret immediately, as it is visible only once. After you leave the screen, the consumer secret will not be visible anymore.

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

   • The 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, the user is enabled to operate orders through the order manager by means of GET and POST requests:

   

   Note

   1. This restriction concerns only Custom Operations and does not do anything with the CRUD.

   2. When adding an allowed operation, omit the APS type version in the APS Type field.

   3. To configure APS Bus Access, a staff member must be granted the “OAuth APS Bus Access”=”Manage” privilege.

Choose a 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.

  This 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 compatible with the RQL parser.

Sample Scripts

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

For example, in a Python script, use the requests_oauthlib module that you can install through the Python package manager using:

$ sudo pip install requests_oauthlib

GET Request

A simple Python script that gets all available APS resources may look as follows:

#!/usr/bin/env python

from requests_oauthlib import OAuth1Session

# Enter input parameters:
consumer_key = 'ug7nnV3aq4VwGQQzyiFRDSGwa7QZY0YE'
consumer_secret = 'cccMHKhIIVupWAEWtYeQmg9DVe0DSP...'   # Cut for brevity
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

POST Request

Similarly, the following script sends a POST request on placing a sales order to subscribe an account to a service plan:

#!/usr/bin/env python

from requests_oauthlib import OAuth1Session

consumer_key = 'qcrtTudBOCeRTh0rhQSEuSMucj7uNxSy'
consumer_secret = '6X9Zspqd81NoJJ0EGMHvm2kWRqy...'  # Cut for brevity

url = 'https://a.isv1.apsdemo.org/aps/2/services/order-manager/orders'

session = OAuth1Session(client_key=consumer_key, client_secret=consumer_secret)

order = {
    "type": "SALES",
    "accountId": "992d543f-e5e7-4439-a139-38b364ce49af",
    "products": [
        {
            "planId": "6a8513fd-c222-42f0-ab47-985477e807c6",
            "period": {
                "unit": "MONTHS",
                "duration": 1
            },
            "resources": [
                {
                    "resourceId": "29086bff-284d-4d6b-ad59-404bbbda2152",
                    "amount": 10
                },
                {
                    "resourceId": "cb2ffba9-4f25-411c-b49d-418f2ec36f4b",
                    "amount": 3
                }
            ]
        }
    ]
}

response = session.post(url, json=order, verify=False)
print(response.text)

Video

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

Sample GUI Client

You can also find a GUI tool that meets the above requirements. A GUI client helps you test selected key operations before implementing them in a management system. For example, the Insomnia REST client meets all the above requirements; it is used in the following example.

The preferences and request settings of Insomnia allow you to disable validation of SSL certificates and disable URL encoding.

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 to construct all other fields for the Authorization header.

← Using APS REST API

Authorization through IDP →