Skip to content

getting-started.md

Latest commit

 

History

History
122 lines (75 loc) · 5.36 KB

getting-started.md

File metadata and controls

122 lines (75 loc) · 5.36 KB

Getting Started with SimpleAuth for .NET

Note from the Developer: This is a very early release and this process will improve over time! Please let me know if you have any constructive feedback. Also note that these instructions are for installation on Windows environments.

Prerequisites

The following software packages are required to follow along with this documentation:

Step 1: Download the repo

git clone https://github.com/lymestack/SimpleAuth4Net.git
cd SimpleAuth4Net

Step 2: Generate a "Token Secret"

First start by replacing the value of the TokenSecret config setting in the App Settings file with randomly generated 64 byte (or more) secret.

To generate a random secret, you can use the provided Powershell or Python scripts.

In Powershell:

Note: In Powershell, per this article, you will need to run this Powershell command on your computer prior to running the next command: Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

.\generate-token-secret.ps1

In Python:

python generate-token-secret.py

Sample Output:

Generating a secure TOKEN_SECRET...
TOKEN_SECRET: 9as8ma2iRGZypKiAGdivENIQ1lMEqJsmtMQ25J8A/W0SKoqVu11IeWLkG1nYypgoOSFY3DIFqOshK57HZMLI6g==
Copy the above TOKEN_SECRET and use it in your application.

Copy the TOKEN_SECRET value generated by the program and paste that value into the AuthSettings:TokenSecret node in the WebApi/WebApi/appsettings.json App Settings file.

Step 3: Setup your Database

Note: If you are following along in a non-Windows environment, you'll need to run SQL Server for Linux either natively on a Linux instance or within a Docker container.

  1. Open SSMS and connect to the .\SQLEXPRESS instance.
  2. Create a new database or pick an existing database. For this doc, we are creating a new database called SimpleAuth.
  3. Right click the new database and select the "New Query" option.
  4. Copy the contents of the file CreateDb.sql (located in the repo root directory) into the query window and press F5 to run the query.

Step 4: Run the API & App

There is more than one way to go about this. For this tutorial, there are two ways that will be recommended.

Quick Start

  1. Run the Run.bat file in your repository root. This will open two terminal windows that automate the steps described in the Manual Start instructions below. At this point you should see the home page of the Angular App and you can skip ahead to Step 5.

Manual Start

Follow the following steps to run the app manually.

Run the API

Open a new command window in the WebApi folder located in root of the repo.

dotnet run --project WebApi

In your browser, navigate to: https://localhost:7214/AppConfig

At this point you should see JSON configuration data and the API should be up and running.

Run the Client App

There are currently 3 sample SPA apps that can authenticate with the API - Angular, react and VueJS. Currently, the Angular version is the most polished of the implementations whereas the React and Vue apps are more simplistic and academic in nature. The Angular client app also includes UI to administer users and roles. This guide only covers getting the Angular app up and running, but instructions to run the React and Vue apps are on their respective documentation pages.

Open another command window in ng-app folder located in the root of the repo

npm install
npm start

In your browser, navigate to: http://localhost:4200

At this point you should see the home page of the Angular App.

Step 5: Test Authentication Failure

  1. Once the app loads, click the "Test Secure Resource" button to demonstrate an attempt to reach a secure endpoint on the API. You should receive a red error message indicating that the resource could not be accessed.

Step 6: Create your First User

  1. On the home page, click the "Login" button and then the "Register" button.
  2. Fill out your information and click the Submit button. By default, the first user created in the system will be given "Admin" role access.

Step 7: Login to the Application

  1. Click the "Login" link.
  2. Enter the credentials you just created.
  3. After logging in, click the "Test Secure Resource" button. You should receive a success message saying that the endpoint worked.

That's it! At this point, you should have Auth up and running on your local machine!

Optional - Configure Google SSO

Instructions for configuring this can be found on the Google SSO page.