remote-monitoring-services-dotnet/auth

PCS Authentication and Authorization Overview

This service allows to manage the users authorized to access Azure IoT Solutions. Users management can be done using any identity service provider supporting OpenId Connect.

Dependencies

The service depends on:

• Azure Active Directory used to store users and providing the certificates to validate JWT tokens signature. Any identity provider supporting OpenId Connect should work though.
• Configuration settings to define the trusted Issuer and expected Audience.

How to use the microservice

Quickstart - Running the service with Docker

1. Create an instance of Azure Active Directory or simply reuse the instance coming with your Azure subscription
2. Register an application in AAD
3. Get the Application ID and Issuer URL and store them in the service configuration.
4. Install Docker
5. Start the Auth service using docker compose:

   cd scripts (in the auth folder)
   cd docker
   docker-compose up OR
   run.cmd (win) OR
   ./run (Linux / Mac OS)
   

6. Use an HTTP client such as Postman, to exercise the RESTful API.

Running the service with Visual Studio or VS Code

1. Install .NET Core 2.x
2. Install any recent edition of Visual Studio (Windows/MacOS) or Visual Studio Code (Windows/MacOS/Linux).
   • If you already have Visual Studio installed, then ensure you have .NET Core Tools for Visual Studio 2017 installed (Windows only).
   • If you already have VS Code installed, then ensure you have the C# for Visual Studio Code (powered by OmniSharp) extension installed.
3. Create an instance of Azure Active Directory or simply reuse the instance coming with your Azure subscription
4. Open the solution in Visual Studio or VS Code.

Environment variables required to run the service

In order to run the service, some environment variables need to be created at least once. See specific instructions for IDE or command line setup below for more information. More information on environment variables here.

• PCS_AAD_APPID = { Azure service principal id }
• PCS_AAD_APPSECRET = { Azure service principal secret }
• PCS_KEYVAULT_NAME = { Name of Key Vault resource that stores settings and configuration }

Configuration values used from Key Vault

Some of the configuration needed by the microservice is stored in an instance of Key Vault that was created on initial deployment. The auth microservice uses:

• aadAppId = Azure Active Directory application / service principal id.
• aadAppSecret = Azure Active Directory service princial secret.
• aadEndpointUrl = The AAD endpoint url to acquire ARM token for AAD application.
• authIssuer = Identifies the security token service (STS) i.e. https://sts.windows.net/{tenantId}/.
• aadTenantId = GUID representing your active directory tenant.
• authRequired = Whether or not authentication is needed for calls to microservices i.e. from the web ui or postman.
• corsWhitelist = Specifies where requests are allowed from "{ 'origins': ['*'], 'methods': ['*'], 'headers': ['*'] }" to allow everything. Empty to disable CORS.

Project Structure

The solution contains the following projects and folders:

• WebService: ASP.NET Web API exposing a RESTful API for Authentication functionality, e.g. show the current user profile.
• Services: Library containing common business logic for interacting with Azure Active Directory.
• WebService.Test: Unit tests for the ASP.NET Web API project.
• Services.Test: Unit tests for the Services library.
• scripts: a folder containing scripts from the command line console, to build and run the solution, and other frequent tasks.

Build and Run from the command line

The scripts folder contains scripts for many frequent tasks:

• build: compile all the projects and run the tests.
• compile: compile all the projects.
• run: compile the projects and run the service. This will prompt for elevated privileges in Windows to run the web service.

Building a customized Docker image

The scripts folder includes a docker subfolder with the scripts required to package the service into a Docker image:

• Dockerfile: Docker image specifications
• build: build a Docker image and store the image in the local registry
• run: run the Docker container from the image stored in the local registry
• content: a folder with files copied into the image, including the entry point script

Configuration and Environment variables

The service configuration is stored using ASP.NET Core configuration adapters, in appsettings.ini. The INI format allows to store values in a readable format, with comments.

Configuration in appsettings.ini are typically set in 3 different ways:

1. Environment variables as is the case with ${PCS_AAD_APPID}. This is typically only done with the 3 variables described above as these are needed to access Key Vault. More details about setting environment variables are located below.
2. Key Vault: A number of the settings in this file will be blank as they are expecting to get their value from a Key Vault secret of the same name.
3. Direct Value: For some values that aren't typically changed or for local development you can set the value directly in the file.

Depending on the OS and the IDE used, there are several ways to manage environment variables.

1. If you're using Visual Studio or Visual Studio for Mac, the environment variables are loaded from the project settings. Right click on WebService, and select Options/Properties, and find the section with the list of env vars. See WebService/Properties/launchSettings.json.
2. Visual Studio Code loads the environment variables from .vscode/launch.json
3. When running the service with Docker or from the command line, the application will inherit environment variables values from the system.
   • Depending on OS and terminal, there are different ways to persist values globally, for more information these pages should help:
     • https://superuser.com/questions/949560/
     • https://stackoverflow.com/questions/13046624/how-to-permanently-export-a-variable-in-linux
     • https://stackoverflow.com/questions/135688/setting-environment-variables-in-os-x
     • https://help.ubuntu.com/community/EnvironmentVariables
4. IntelliJ Rider: env. vars can be set in each Run Configuration, similarly to IntelliJ IDEA (https://www.jetbrains.com/help/idea/run-debug-configuration-application.html)

Contributing to the solution

Please follow our contribution guidelines. We love PRs too.

Troubleshooting

{TODO}

Feedback

Please enter issues, bugs, or suggestions as GitHub Issues here: https://github.com/Azure/pcs-auth-dotnet/issues.