Service Connector

The provisioning type is selected when setting up a new service. The provisioning type defines the action when a customer subscribes to a service. Currently, there are two options, email or Service Connector. The email option sends an email to a nominated email address containing the provisioning information. The service connector allows for your REST API call to be made to transfer the same service information to your 3rd party system. This document walks you through the Service Connector option and the available API calls. The user should be able to access or create middle ware that takes the provisioning data from Cloudmore, provisions the service and returns the result back to Cloudmore.

Important

Cloudmore only provides detailed information about how to setup the Service Connector and the description of the API calls. It’s the user’s responsibility to provide and manage the REST API to receive the API calls. Cloudmore has created a solution, built on standard, available technologies, and a workflow that integrates with the services setup procedure. Cloudmore cannot incorporate bespoke or special configuration or changes.

Test application

Cloudmore provides a test application that can be used as a reference point for implementation. The test application is a REST API built in .NET that will receive calls from Cloudmore and store them temporarily. The test client cannot be used for live implementations, but can be used during development to show the data sent in API requests.

Cloudmore provides both the source code and test client as is with no warranties or guarantees.

Security

Cloudmore has built the Service Connector security on OAuth2 standard grant type called “client credentials.” OAuth 2.0 is the industry-standard protocol for authorization and enables a secure authentication between Cloudmore and your 3rd party system.

Your 3rd party system needs to be able to handle the authentication request from Cloudmore and issue an access token in JSON format (a JSON Web Token or JWT).

Cloudmore has developed the Service Connector using IdentiyServer4 (http://docs.identityserver.io), an OpenID and OAuth 2.0 framework for ASP.NET Core. This is one example of how the OAuth2 framework can be used.

To further ensure the security, all data is encrypted in transmission, all requests must be performed over HTTPS. 

The client grant type requires three key pieces of information:

1. Client ID – The client ID is generated by the 3rd party system as an ID for the Cloudmore platform.
2. Client Secret – The client secret is similar to a password used for the client ID. It is also generated by the 3rd party system. The client secret is maintained within Cloudmore in encrypted form and decrypted only when a request is sent. The client secret cannot exceed 20 characters in length.
3. Authorization URL (or endpoint) – This is the address (URL) that Cloudmore will use to request and obtain an access token. Example: https://3rdpartydomain.com/authentication/token/

Service connector Setup  in Cloudmore

To setup the security properties, login to Cloudmore and go to Services on seller level or Custom Services on reseller level. Then, add a new service and select “Service Connector” under Provisioning Type. You will then get a form that looks like this:

1. Client id – Enter the client Id generated by the 3rd party system.
2. Client Secret – Enter the client secret generated by the 3rd party system.
3. Authorization URL – Enter the URL to the 3rd party OAuth2 server.
4. Custom Service URL – Enter the URL where to send provisioning request to. Example: https://3rdpartydomain.com/api/customservice/
5. User Subscription URL (Only visible if you have selected “User assigned service”) – Enter the URL where provisioning of users should be sent. Example: https://3rdpartydomain.com/api/usersubscription/

Create the Service and add products. Click on the “Manage products” (book) icon next to the service. Complete the form. When you get to “provisioning management” section, fill in the “REST API Subscription URL.” This is the URL specific to this product. Example: https://3rdpartydomain.com/api/subscriptions/

Note: The Service Connector supports custom properties. You can add custom properties to a product to send additional data to the API. Custom properties can be visible or hidden to the user.

Provisioning Events

An API call should be triggered by certain events in Cloudmore. Below is a list of events and the API call that is triggered.

Note: All the Service Connector calls will fail if a valid authorization access token is not sent with each call. In all such cases, the response code would be 401 – Unauthorized.

Cloudmore will expect the 3rd party system to respond with a response code to indicate the outcome of the API call. Also, for some calls, the 3rd party system might need to send a data response.

Default data provided in Service Connector Request Body by Procedure

Cloudmore will include the following data in JSON format in the body of the HTTP request in the following events:

Organization adds a service