Application Authentication

The service manager is available to all the tenants of interworks.cloud platform. This means that all the companies who use the interworks.cloud platform (e.g.: distributors or resellers of cloud services, etc.) can activate an instance of the service manager and automate the delivery of the underlying service. The service manager you will implement is considered a separate application which needs to take security issues under consideration and protect itself against possible vulnerabilities.

To ensure that all security aspects will be clearly defined, the interworks.cloud Platform separates the Authorization and Authentication processes during communication with a service manager.

• The authorization process is generally used to identify an interworks.cloud platform installation. It is based on the Application Id and API Key info generated during new application registration.
• The authentication process is responsible for identifying which of your partners will use your service manager. An interworks.cloud platform installation can be used by several companies, since we offer an online edition for our platform. In this case, It is necessary from your side to distinguish who is activating and using the service manager for assigning and managing the necessary services.

On this page, we will explain which end-points you need to implement for defining the authentication parameters of your service manager:

1. Get Setting Fields: This endpoint describes the input fields required for the authentication of your application.
2. Validate Setting Fields: This endpoint performs the authentication of your partner.

“Get Services Fields” Endpoint

swagger documentation: GET /API/Fields/Get

This endpoint describes the input fields required for the authentication of your application. These fields will be used for constructing the Settings page of your service manager. This is the page where your partner will enter his authentication credentials for activating your service manager.

Authentication Fields

The setting fields returned from this endpoint depend on the authentication mechanism of your application’s provisioning and management API. It can be as simple as a username and password, a token, or even to require your partner to upload a Client Certification. Most of the values are sent as clear text values to calls performed from Service Management API. Transport security is mainly based on HTTPS Access and IP Restriction rules that could be applied from your side.

Provisioning Related Fields

The setting fields can also be used to gather information necessary for the provisioning flows of your application. For example, if you have deployed your application to multiple data centers, you may need to define in which data center the services will be activated. Or, if the availability of your products depends on a specific location, you might need to arrange the service provisioning according to the user’s geographical location. In these scenarios, you should define setting fields for collecting the necessary information from your partner during the activation of your service manager.

Displaying Setup Fields Based on Hierarchy

By default, the fields retrieved from a Service Manager are only displayed in the root instance. To display a setup field in a tenant instance (Country Tenant or Tenant Reseller), set the AllowOverride property to true. To display a setup field only in a tenant reseller instance, set the IsResellerOption property to true.

The table below summarizes the display of Setup Fields based on the values of the two fields:

Field Definition	Root Instance	Country Tenant	Tenant Reseller
FieldDefinition.AllowOverride=false FieldDefinition.IsResellerOption=false (default)
FieldDefinition.AllowOverride=true
FieldDefinition.IsResellerOption=true

“Validate Setting Fields“ Endpoint

Swagger documentation: POST ​/api​/Fields​/Validate

This endpoint performs validation of the authentication inputs provided by your partner. If the validation fails, an error message must be returned to explain the cause of the failure to your partner. The validation is performed when your partner will save the settings of your service manager.

“Get Additional Info” Endpoint

Swagger documentation: GET api/Fields/AdditionalInfo

This endpoint is called to collect any additional info related to the given authentication configuration (e.g. Company profile info).

Any fields containing additional information will also have to be added to the Get Services Fields request under Fields. For example, adding the header “Profile” requires adding the following to the Get Services Fields request JSON:

{
  "Fields":[
    {
      "ID":"profileId",
      "Name":"profileId",
      "Kind":"Hidden"
    }
  [
}

This info is stored in the platform with the authentication inputs collected by the user. Similar to authentication inputs, the stored additional info is available to other endpoint HTTP requests via X-CloudPlatform-Setting-* HTTP headers.

Example Response:

{
  "Currency": "EUR",
  "Profile": "23",
  "Pricelist": "pricelist_global"
}

The endpoint is called after the Validate Settings endpoint.