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

Create an instance of Azure Active Directory or simply reuse the instance coming with your Azure subscription
Register an application in AAD
Get the Application ID and Issuer URL and store them in the service configuration.
Install Docker
Start the Auth service using docker compose:
```
cd scripts
cd docker
run
```
Use an HTTP client such as Postman, to exercise the RESTful API.

Running the service with Visual Studio

Install any edition of Visual Studio 2017 or Visual Studio for Mac. When installing check ".NET Core" workload. If you already have Visual Studio installed, then ensure you have .NET Core Tools for Visual Studio 2017 installed (Windows only).
Create an instance of Azure Active Directory or simply reuse the instance coming with your Azure subscription
Get the Application ID and Issuer URL and store them in the service configuration.
Open the solution in Visual Studio
In Visual Studio, start the WebService project
Use an HTTP client such as Postman, to exercise the RESTful API.

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 and appsettings.ini. The INI format allows to store values in a readable format, with comments. The application also supports references to environment variables, which is used to import credentials and networking details.

The configuration files in the repository reference some environment variables that need to be created at least once. Depending on your OS and the IDE, there are several ways to manage environment variables:

Windows: the variables can be set in the system as a one time only task. The env-vars-setup.cmd script included needs to be prepared and executed just once. The settings will persist across terminal sessions and reboots.
Visual Studio: the variables can be set in the projects's settings, both WebService and SimulationAgent, under Project Propertie -> Configuration Properties -> Environment
For Linux and OSX environments, the env-vars-setup script needs to be executed every time a new console is opened. Depending on the OS and terminal, there are ways to persist values globally, for more information these pages should help:

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.

trbenning/pcs-auth-dotnet