Manual SCC Setup

This document describes the detailed steps to setup the Swarm Control Center via the Azure Web UI.

Enterprise Application

  1. Open https://portal.azure.com/ and navigate to the AD overview.

  2. Select "New Application", "Add your own application", and proceed to the App registration.

  3. Select "New registration" and fill in desired values. The Redirect URI is required and determines where you can access SCC in your browser.

  4. Take not of the "Directory (Tenant) ID" and the "Application (client) ID" in the following page.

  5. Make the following configuration changes under the respective points:

    1. Under the point "Authentication, enable "Access tokens" and "ID tokens".

    2. Under the point "Certificates & Secrets", create a new Client Secret.

    3. For the point "Manifest", replace the following elements with the given examples and confirm the changes under the point "API Permissions". This enables the API to validate Users against roles against assigned roles.

"requiredResourceAccess": [
{
"resourceAppId": "00000003-0000-0000-c000-000000000000",
"resourceAccess": [
{
"id": "14dad69e-099b-42c9-810b-d002981feec1",
"type": "Scope"
},
{
"id": "741c54c3-0c1e-44a1-818b-3f97ab4e8c83",
"type": "Scope"
},
{
"id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
"type": "Scope"
}
]
}
],
"appRoles": [
{
"allowedMemberTypes": [
"User"
],
"description": "Superadmins can manage everything.",
"displayName": "Superadmin",
"id": "659bb81e-c66f-46ea-bf05-a7f6fa1698aa",
"isEnabled": true,
"lang": null,
"origin": "Application",
"value": "superadmin"
},
{
"allowedMemberTypes": [
"User"
],
"description": "Operators can maintain boxes.",
"displayName": "Operator",
"id": "318606d6-c6b1-487a-a34c-501f3bbf7a57",
"isEnabled": true,
"lang": null,
"origin": "Application",
"value": "operator"
}
],

Assign roles in your newly created Enterprise Application ("Users and groups") to existing users who should be able to access the SCC. This can changed at any later time.

Following this basic setup, we can now configure the web applications.

Setup Web Applications

There are two required web applications (frontend and API gateway) that should be created. Note that the frontend name should correspond to the reply URI used during the definition of your AD application.

API Gateway

Assign roles in your newly created Enterprise Application ("Users and groups") to existing users who should be able to access the SCC. This can changed at any later time.

  1. On the Azure Portal create a new App Service in the previously defined resource group. Give it a suitable name (e.g. swarm-control-center-example-api). Select "Docker Container" as publish type, Linux as operating system, and (ideally) the region of the IoT Hub.

  2. Create a new App Service Plan. This can provide the infrastructure for the gateway and frontend application. As minimum we recommend a Basic B1 instance.

  3. In the next step ("Docker") select "Single Container" and "Private Registry. Enter the provided credentials and version details for the API Gateway.

  4. Review entries and create the application. The deployment should be ready in in a couple of minutes. Go to the created resource afterwards.

Under "Configuration" add the following application settings. Fill in the values from setting up your IoT Hub (for the IoT Hub Connection String) and the registration of your application in AD.

ADD_TENANT_ID
ADD_APP_CLIENT_ID
IOT_HUB_CONNECTION_STRING

Finally, either integrate the API into existing API Managment on Azure or set up CORS access manually (with the URI picked as Redirect URI, e.g.: https://swarm-control-center-example.azurewebsites.net/).

SCC Frontend

Create a second Web App, following the steps for the API gateway.

  1. As name pick the value set for the Redirect URI during AD setup. E.g.: swarm-control-center-example.azurewebsites.net.

  2. Use the same App Service Plan.

  3. When setting the docker image, follow the settings of the API gateway, but enter the credentials and version details provided for the SCC frontend.

  4. Review entries and create the application. The deployment should be ready in in a couple of minutes. Go to the created resource afterwards.

Under "Configuration" add the following application settings.

REACT_APP_AAD_APP_CLIENT_ID
REACT_APP_API_URL
REACT_APP_AUTHORITY

As values use :

  • REACT_APP_ADD_APP_CLIENT_ID: The Application ID generated during setup in AD.

  • REACT_APP_API_URL: Based on the the value chosen for the API gateway. Note: This has to include the protocol and the version of the API. E.g. https://swarm-control-center-example-api.azurewebsites.net/v1/

  • REACT_APP_AUTHORITY: https://login.microsoftonline.com/<TENANT-ID> with your Azure Tenant ID (see the configuration of the API gateway and setup of your AD Enterprise Application).

‚Äč