This is guest post written originally to Auth0.
Recently I’ve blogged about using tokens to authenticate users in single page applications, I’ve used ASP.NET Web API, Owin middleware and ASP.NET Identity to store local accounts in database, I didn’t tap into social identity logins such as (Google, Microsoft Accounts, Facebook, etc..) because each provider will not supply the same information (profile schema) about the logged in user, there might be properties missing or with different names, so handling this manually and storing those different schemes will not be a straight forward process.
I was introduced to Auth0 by Matias Woloski, basically Auth0 is a feature rich identity management system which supports local database accounts, integration with more than 30 social identity providers, and enterprise identity providers such as (AD, Office 365, Google Apps, etc…). You can check the full list here.
In this post I’ll implement the same set of features I’ve implemented previously using Auth0 management system as well I’ll integrate authentication with multiple social identity providers using less code in the back-end API and in the front-end application which will be built using AngularJS. So let’s jump to the implementation.
I’ll split this post into two sections, the first section will be for creating the back-end API and configuring Auth0 application, and the second section will cover creating the SPA and Auth0 widget.
The demo application we’ll build in this post can be accessed from (http://auth0web.azurewebsites.net). The source code is available on my GitHub Repo.
Section 1: Building the Back-end API
Step 1.1: Create new Application in Auth0
After you register with Autho you need to create an application, Auth0 comes with set of applications with easy to integrate SDKs, in our case we’ll select “ASP.NET (OWIN)” application as the image below:
After you give the application a friendly name, in my case I named it “ASP.NET (OWIN)” a popup window will show up asking which connections you want to enable for this application. “Connection” in Auth0 means identity providers you want to allow in the application, in my case I’ll allow Database local accounts, Facebook, Google, GitHub, and Microsoft Accounts as the image below. Usually the social accounts will be disabled for all applications, to enable them navigate to “Connections” tab, choose “Social” then enable the social providers you like to enable for your application.
Once the application is created, you can navigate to application “settings” link where you will find all the needed information (Domain, Client Id, Client Secret, Callback URLs, etc…) to configure the Web API we’ll build in the next step.
Step 1.2: Create the Web API
In this tutorial I’m using Visual Studio 2013 and .Net framework 4.5, you can follow along using Visual Studio 2012 but you need to install Web Tools 2013.1 for VS 2012 by visiting this link.
Now create an empty solution and name it “AuthZero” then add new ASP.NET Web application named “AuthZero.API”, the selected template for the project will be “Empty” template with no core dependencies, check the image below:
Step 1.3: Install the needed NuGet Packages
This project is empty so we need to install the NuGet packages needed to setup our Owin server and configure ASP.NET Web API to be hosted within an Owin server, so open NuGet Package Manager Console and install the below packages:
Install-Package Microsoft.AspNet.WebApi -Version 5.1.2 Install-Package Microsoft.AspNet.WebApi.Owin -Version 5.1.2 Install-Package Microsoft.Owin.Host.SystemWeb -Version 2.1.0 Install-Package Microsoft.Owin.Security.Jwt -Version 2.1.0 Install-Package Microsoft.Owin.Cors -Version 2.1.0 Update-Package System.IdentityModel.Tokens.Jwt
The first package “Microsoft.AspNet.WebApi” contains everything we need to host our API on IIS, the second package “Microsoft.AspNet.WebApi.Owin” will allow us to host Web API within an Owin server.
The third package “Microsoft.Owin.Host.SystemWeb” will be used to enable our Owin server to run our API on IIS using ASP.NET request pipeline as eventually we’ll host this API on Microsoft Azure Websites which uses IIS.
The forth package “Microsoft.Owin.Security.Jwt” will enable Owin server Middleware to protect and validate JSON Web Tokens (JWT).
The last package “Microsoft.Owin.Cors” will be responsible to allow CORS for our Web API so it will accept requests coming from any origin.
Note: The package “System.IdentityModel.Tokens.Jwt” gets installed by default is old (version 1.0.0) so we need to update it to latest (version 3.0.2).
Step 1.4: Add Auth0 settings to Web.config
We need to read the Auth0 settings for the application we created earlier to configure our API, so open Web.Config file and add the below keys, do not forget to replace the values of those keys with the correct one you obtain once you create application on Auth0.
<appSettings>
<add key="auth0:ClientId" value="YOUR_CLIENT_ID" />
<add key="auth0:ClientSecret" value="YOUR_CLIENT_SECRET" />
<add key="auth0:Domain" value="YOUR_DOMAIN" />
</appSettings>
Step 1.5: Add Owin “Startup” Class
Now we want to add new class named “Startup”. It will contain the code below:
[assembly: OwinStartup(typeof(AuthZero.API.Startup))]
namespace AuthZero.API
{
public class Startup
{
public void Configuration(IAppBuilder app)
{
HttpConfiguration config = new HttpConfiguration();
ConfigureAuthZero(app);
WebApiConfig.Register(config);
app.UseCors(Microsoft.Owin.Cors.CorsOptions.AllowAll);
app.UseWebApi(config);
}
}
}What we’ve implemented above is simple, this class will be fired once our server starts, notice the “assembly” attribute which states which class to fire on start-up. The “Configuration” method accepts parameter of type “IAppBuilder” this parameter will be supplied by the host at run-time. This “app” parameter is an interface which will be used to compose the application for our Owin server.
The implementation of method “ConfigureAuthZero” will be covered in the next step, this method will be responsible to configure our Web API to generate JWT using Auth0 application we created earlier.
The “HttpConfiguration” object is used to configure API routes, so we’ll pass this object to method “Register” in “WebApiConfig” class.
Lastly, we’ll pass the “config” object to the extension method “UseWebApi” which will be responsible to wire up ASP.NET Web API to our Owin server pipeline.
The implementation of “WebApiConfig” is simple, all you need to do is to add this class under the folder “App_Start” then paste the code below:
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
// Web API routes
config.MapHttpAttributeRoutes();
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
var jsonFormatter = config.Formatters.OfType<JsonMediaTypeFormatter>().First();
jsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
}
}
Step 1.6: Configure generating JWT using Auth0
Now we want to configure our Web API to use Auth0 application created earlier to generate JSON Web Tokens which will be used to allow authenticated users to access the secured methods in our Web API. So to implement this open class “Startup” and add the code below:
//Rest of Startup class implementation is here
private void ConfigureAuthZero(IAppBuilder app)
{
var issuer = "https://" + ConfigurationManager.AppSettings["auth0:Domain"] + "/";
var audience = ConfigurationManager.AppSettings["auth0:ClientId"];
var secret = TextEncodings.Base64.Encode(TextEncodings.Base64Url.Decode(ConfigurationManager.AppSettings["auth0:ClientSecret"]));
// Api controllers with an [Authorize] attribute will be validated with JWT
app.UseJwtBearerAuthentication(
new JwtBearerAuthenticationOptions
{
AuthenticationMode = Microsoft.Owin.Security.AuthenticationMode.Active,
AllowedAudiences = new[] { audience },
IssuerSecurityTokenProviders = new IIssuerSecurityTokenProvider[]
{
new SymmetricKeyIssuerSecurityTokenProvider(issuer, secret)
}
});
}What we’ve implemented in this method is the following:
- Read Autho application settings stored in the web.config file.
- We’ve added the JSON Web Token Bearer middleware to our Owin server, this class accepts set of options, as you can see we’ve set the authentication mode to “Active” which configures the middleware to check every incoming request and attempt to authenticate the call, and if it is successful, it will create a principal that represents the current user and assign that principal to the hosting environment.
- We’ve set the issuer of our JSON Web Token (Domain Name) along with the base64 encoded symmetric key (Client Secret) which will be used to sign the generated JSON Web Token.
Now if we want to secure any end point in our Web API, all we need to do is to attribute any Web API controller with “[Authorize]” attribute, so requests containing a valid bearer token can only access it.
Note: The JWT Token expiration time can be set from Autho Application settings as the image below, the default value is 36000 seconds (10 hours).
Step 1.7: Add a Secure Shipments Controller
Now we want to add a secure controller to serve our Shipments, we’ll assume that this controller will return shipments only for authenticated users, to keep things simple we’ll return static data. So add new controller named “ShipmentsController” and paste the code below:
[RoutePrefix("api/shipments")]
public class ShipmentsController : ApiController
{
[Authorize]
[Route("")]
public IHttpActionResult Get()
{
return Ok(Shipment.CreateShipments());
}
}
#region Helpers
public class Shipment
{
public int ShipmentId { get; set; }
public string Origin { get; set; }
public string Destination { get; set; }
public static List<Shipment> CreateShipments()
{
List<Shipment> ShipmentList = new List<Shipment>
{
new Shipment {ShipmentId = 10248, Origin = "Amman", Destination = "Dubai" },
new Shipment {ShipmentId = 10249, Origin = "Dubai", Destination = "Abu Dhabi"},
new Shipment {ShipmentId = 10250,Origin = "Dubai", Destination = "New York"},
new Shipment {ShipmentId = 10251,Origin = "Boston", Destination = "New Jersey"},
new Shipment {ShipmentId = 10252,Origin = "Cairo", Destination = "Jeddah"}
};
return ShipmentList;
}
}
#endregionNotice how we added the “Authorize” attribute on the method “Get” so if you tried to issue HTTP GET request to the end point “http://localhost:port/api/shipments” you will receive HTTP status code 401 unauthorized because the request you sent till this moment doesn’t contain JWT in the authorization header. You can check it using this end point: http://auth0api.azurewebsites.net/api/shipments
Step 1.8: Add new user and Test the API
Auth0 dashboard allows you to manage users registered in the applications you created under Auth0, so to test the API we’ve created we need to create a user before, I’ll jump back to Auth0 dashboard and navigate to the “Users” tab then click “New”, a popup window will appear as the image below, this window will allow us to create local database user, so fill up the form to create new user, I’ll use email “taiseer.joudeh@hotmail.com” and password “87654321”.
Once the user is created we need to generate JWT token so we can access the secured end point, to generate JWT we can send HTTP POST request to the end point https://tjoudeh.auth0.com/oauth/ro this end point will work only for local database connections and AD/LDAP. You can check Auth0 API playground here. To get JWT token open your favorite REST client and issue POST request as the image below:
Notice that the content-type and payload type is “x-www-form-urlencoded” so the payload body will contain encoded URL, as well notice that we’ve specified the “Connection” for this token and the “grant_type” If all is correct we’ll received JWT token (id_token) on the response.
Note: The “grant_type” indicates the type of grant being presented in exchange for an access token, in our case it is password.
Now we want to use this token to request the secure data using the end point http://auth0api.azurewebsites.net/api/shipments so we’ll issue GET request to this end point and will pass the bearer JWT token in the Authorization header, so for any secure end point we have to pass this bearer token along with each request to authenticate the user.
The GET request will be as the image below:
If all is correct we’ll receive HTTP status 200 Ok along with the secured data in the response body, if you try to change any character with signed token you directly receive HTTP status code 401 unauthorized.
By now our back-end API is ready to be consumed by the front-end app we’ll build in the next section.
Section 2: Building the Front-end SPA
Now we want to build SPA using AngularJS which will communicate with the back-end API created earlier. Auth0 provides a very neat and feature rich JavaScript plugin named “Widget“. This widget is very easy to implement in any web app. When you use it you will get features out of the box such as social integration with social providers, integration with AD, and sign up/forgot password features. The widget plugin looks as the image below:
The enabled social login providers can be controlled from Autho dashboard using the “Connection” tab, so for example if you want to enable LinkedIn, you just need to activate it on your Auth0 application and it will show directly on the Widget.
Step 2.1: Add the Shell Page (Index.html)
First of all, we need to add the “Single Page” which is a container for our application, this page will contain a link to sign in, a section will show up for authenticated users only, and “ng-view” directive which will be used to load partial views. The html for this page will be as the below:
<!DOCTYPE html>
<html>
<head>
<link href="content/app.css" rel="stylesheet" />
<link href="https://netdna.bootstrapcdn.com/bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
</head>
<body ng-app="auth0-sample" class="home" ng-controller="mainController">
<div class="login-page clearfix">
<div class="login-box auth0-box" ng-hide="loggedIn">
<img src="https://i.cloudup.com/StzWWrY34s.png" />
<h3>Auth0 Example</h3>
<p>Zero friction identity infrastructure, built for developers</p>
<a ng-click="login()" class="btn btn-primary btn-lg btn-block">SignIn</a>
</div>
<!-- This log in page would normally be done using routes
but for the simplicity of the excercise, we're using ng-show -->
<div ng-show="loggedIn" class="logged-in-box auth0-box">
<img ng-src="{{auth.profile.picture}}" class="avatar"/>
<h3>Welcome {{auth.profile.name}}</h3>
<div class="profile-info row">
<div class="profile-info-label col-xs-6">Nickname</div>
<div class="profile-info-content col-xs-6">{{auth.profile.nickname}}</div>
</div>
<div class="profile-info row">
<div class="profile-info-label col-xs-6">Your JSON Web Token</div>
<div class="profile-info-content col-xs-6">{{auth.idToken | limitTo:12}}...</div>
</div>
<div class="profile-info row">
<a ng-href ="#/shipments" class="btn btn-success btn-sm btn-block">View my shipments</a>
</div>
<div class="profile-info row">
<a ng-click="logout()" class="btn btn-danger btn-sm btn-block">Log out</a>
</div>
</div>
<div data-ng-view="">
</div>
</div>
<script src="https://code.angularjs.org/1.2.16/angular.min.js" type="text/javascript"></script>
<script src="https://code.angularjs.org/1.2.16/angular-cookies.min.js" type="text/javascript"></script>
<script src="https://code.angularjs.org/1.2.16/angular-route.min.js" type="text/javascript"></script>
<script src="app/app.js" type="text/javascript"></script>
<script src="app/controllers.js" type="text/javascript"></script>
</body>
</html>
Step 2.2: Add reference for Auth0-angular.js and Widget libraries
Now we need to add a reference for file Auth0-angular.js, this file is AngularJS module which allows us to trigger the authentication process and parse the JSON Web Token with the “ClientID” we obtained once we created Auth0 application.
As well we need to add a reference for the “Widget” plugin which will be responsible to show the nice login popup we’ve showed earlier. To implement this and at the bottom of “index.html” page add a reference to those new JS files (line 5 and 6) as the code snippet below:
<!--rest of HTML is here--> <script src="https://code.angularjs.org/1.2.16/angular.min.js" type="text/javascript"></script> <script src="https://code.angularjs.org/1.2.16/angular-cookies.min.js" type="text/javascript"></script> <script src="https://code.angularjs.org/1.2.16/angular-route.min.js" type="text/javascript"></script> <script src="https://cdn.auth0.com/w2/auth0-widget-4.js"></script> <script src="https://cdn.auth0.com/w2/auth0-angular-0.4.js"> </script> <script src="app/app.js" type="text/javascript"></script> <script src="app/controllers.js" type="text/javascript"></script>
Step 2.3: Booting up our AngularJS app
We’ll add file named “app.js”, this file will be responsible to configure our AngularJS app, so add this file and paste the code below:
var app = angular.module('auth0-sample', ['auth0-redirect', 'ngRoute']);
app.config(function (authProvider, $httpProvider, $routeProvider) {
authProvider.init({
domain: 'tjoudeh.auth0.com',
clientID: '80YvW9Bsa5P67RnMZRJfZv8jEsDSerDW',
callbackURL: location.href
});
});By looking at the code above you will notice that we’ve injected the dependency “auth0-redirect” to our module, once it is injected we can use the “authProvider” service where we’ll use to configure the widget, so we need to set the values for the domain, clientID, and callBackURL. Those values are obtained from Autho application we’ve created earlier. Once you set the callbackURL you need to visit Auth0 application settings and set the same callbackURL as the image below:
The callbackURL is used once user is successfully authenticated, Auth0 will redirect user to the callbackURL with a hash containing an access_token and the JSON Web Token (id_token).
Step 2.4: Showing up the Widget Plugin
Now it is time to show the Widget once the user clicks on SignIn link, so we need to add file named “controllers.js”, inside this file we’ll define a controller named “mainController”, the implementation for this controller as the code below:
app.controller('mainController', ['$scope', '$location', 'auth', 'AUTH_EVENTS',
function ($scope, $location, auth, AUTH_EVENTS) {
$scope.auth = auth;
$scope.loggedIn = auth.isAuthenticated;
$scope.$on(AUTH_EVENTS.loginSuccess, function () {
$scope.loggedIn = true;
$location.path('/shipments');
});
$scope.$on(AUTH_EVENTS.loginFailure, function () {
console.log("There was an error");
});
$scope.login = function () {
auth.signin({popup: false});
}
$scope.logout = function () {
auth.signout();
$scope.loggedIn = false;
$location.path('/');
};
}]);You can notice that we are injecting the “auth” service and “AUTH_EVENTS”, inside the “login” function we are just calling “auth.signin” and passing “popup:false” as an option, the nice thing here that Auth0-angularjs module broadcasts events related to successful/unsuccessful logins so all child scopes which are interested to listen to this event can handle the login response. So in our case when the login is successful (User is authenticated) we’ll set flag named “loggedIn” to true and redirect the user to a secure partial view named “shipments” which we’ll add in the following steps.
Once the user is authenticated the JSON Web Token and the access token is stored automatically using AngularJS cookie store so you won’t worry about refreshing the single page application and losing the authenticated user context, all this is done by the Widget and Auth0-angularjs module.
Note: To check how to customize the Widget plugin check the link here.
As well we’ve added support for signing out the users, all we need to do is call “auth.signout” and redirect the user to the application root, the widget will take care of clearing the cookie store from the stored token.
Step 2.5: Add Shipments View and Controller
Now we want to add a view which should be accessed by authenticated users only, so we need to add new partial view named “shipments.html”, it will only renders the static data from the end point http://auth0api.azurewebsites.net/api/shipments when issuing GET request. The html for partial view as the below:
<div class="row">
<div class="col-md-4">
</div>
<div class="col-md-4">
<h5><strong>My Secured Shipments</strong> </h5>
<table class="table table-striped table-bordered table-hover">
<thead>
<tr>
<th>Shipment ID</th>
<th>Origin</th>
<th>Destination</th>
</tr>
</thead>
<tbody>
<tr data-ng-repeat="shipment in shipments">
<td>
{{ shipment.shipmentId }}
</td>
<td>
{{ shipment.origin }}
</td>
<td>
{{ shipment.destination }}
</td>
</tr>
</tbody>
</table>
</div>
<div class="col-md-4">
</div>Now open file “controller.js” and add the implementation for “shipmentsController” as the code below:
app.controller('shipmentsController', ['$scope', '$http', '$location', function ($scope, $http, $location) {
var serviceBase = "http://auth0api.azurewebsites.net/";
$scope.shipments = [];
init();
function init() {
getShipments();
}
function getShipments() {
var shipmentsSuccess = function (response) {
$scope.shipments = response.data;
}
var shipmentsFail = function (error) {
if (error.status === 401) {
$location.path('/');
}
}
$http.get(serviceBase + 'api/shipments').then(shipmentsSuccess, shipmentsFail);
}
}]);The implementation for this controller is pretty straight forward. We are just sending HTTP GET request to the secured endpoint http://auth0api.azurewebsites.net/api/shipments, so if the call has succeeded we will set the returned shipments in $scope object named “shipments” and if it failed because the user is unauthorized (HTTP status code 401) then we’ll redirect the user to the application root.
Now to be able to access the secured end point we have to send the JSON Web Token in the authorization header for this request. As you notice we are not setting the token value inside this controller. The right way to do this is to use “AngularJS Interceptors”. Thanks for the Auth0-angularjs module which makes implementing this very simple. This interceptor will allow us to capture every XHR request and manipulate it before sending it to the back-end API so we’ll be able to set the bearer token if the token exists in the cookie store (user is authenticated).
Step 2.6: Add the Interceptor and Configure Routes
All you need to do to add the interceptor is to push it to $httpProvider service interceptors array. Setting the token with each request will be done by Auth0-angularjs module.
As well to configure the shipments route we need to map the “shipmentsController” with “shipments” partial view using $routeProvider service, so open “app.js” file again and replace all the code in it with the code snippet below:
var app = angular.module('auth0-sample', ['auth0-redirect', 'ngRoute', 'authInterceptor']);
app.config(function (authProvider, $httpProvider, $routeProvider) {
authProvider.init({
domain: 'tjoudeh.auth0.com',
clientID: '80YvW9Bsa5P67RnMZRJfZv8jEsDSerDW',
callbackURL: location.href
});
$httpProvider.interceptors.push('authInterceptor');
$routeProvider.when("/shipments", {
controller: "shipmentsController",
templateUrl: "/app/views/shipments.html"
});
$routeProvider.otherwise({ redirectTo: "/" });
});By completing this step we are ready to run the application and see how Auth0 simplified and enriched the experience of users authentication.
If all is implemented correctly, after you are authenticated using social login or database account your profile information and the secured shipments view will look as the image below:
That’s it for now folks!
I hope this step by step post will help you to integrate Auth0 with your applications, if you have any question please drop me a comment.
The post AngularJS Authentication with Auth0 & ASP .Net OWIN appeared first on Bit of Technology.
