Using Microsoft Azure AD for API Authentication with Rails and Warden — Part 1
The current project I am working on at the university is the migration of our Course Marketing Module application from Coldfusion to Ruby. The Course Marketing Module is a bespoke CMS that takes course data from our Student Record System (Ellucian Quercus) to form a base record that is then enhanced with marketing information entered by marketing staff. This is then sent out as an XML feed to the website provider.
We made a decision to take a different approach for this application and use AngularJS on the frontend and build the back end as a Rails API.
One of my first tasks in starting to implement the API was deciding on how to secure it and authenticate requests. We had already made the switch to ADFS for all our Ruby apps and had started to investigate Azure Active Directory so this seemed an obvious choice.
Microsoft have produced a couple of Javascript libraries for using Azure AD in Angular applications. These help you to implement login within your application and query the Microsoft Graph. You can also use this to pass across authentication tokens to your own APIs.
Getting Started
Azure Active Directory Setup
The first thing you need to do is create 2 applications within the Azure Active Directory Portal. One of these will be for the frontend application and the other for the API.
Creating an application
1. In Azure Management Portal, go to Active Directory and select Applications. Click Add at the bottom of the screen.
2. Select ‘Add an application my organisation is developing’
3. Give your application a name and select the ‘Web Application and/or Web API’ option.
4. Provide the sign in URL for the application. This might be something like http://localhost:8000 when running a local dev server.
Enter an App URI, Microsoft recommend using the format http://tenantname.onmicrosoft.com/ApplicationName
5. You should now have an application setup in Azure Active Directory. Repeat this process in the same way to setup another application for the backend.
Setting permissions
In the frontend application you now need to do 2 things, setup Implict Auth Flow and give your frontend application permission to access the API.
- To setup Implict Auth Flow, you need to download the application manifest file. To find this, navigate to your application in Azure AD and then click ‘Manage Manifest’ at the bottom of the screen. Click on Download Manifest.
2. The mainifest comes in the form of a JSON file. Find the key called ‘oauth2AllowImplicitFlow’ and set it to true.
3. Upload the edited manifest file using the ‘Upload Manifest’ option.
4. Click on the ‘Configure’ tab for your application in Azure AD and scroll down to the bottom of the screen to the heading ‘permission to other applications’. Click ‘Add application’
5. Change the application downdown to ‘All Apps’ click on the Tick to the right and then select and add your API application
6. Select the Delegated Permissions permissions dropdown and select ‘Access Application Name API’. Then save your changes
7. You have now setup your application within Azure Active Directory.
Rails API setup
For the Course Marketing Module we are building a standard Rails JSON API built from the rails-api gem. Warden is used as the Authentication middleware that will check the authentication token in our requests.
- In your Gemfile add the following gems
2. Create a new file called `lib/azure_ad_json_web_token.rb`
This gets the public key from the Windows login endpoint which is used to verify that the token was signed by microsoft. You may wish to cache this for 24hrs so it doesn’t get requested on every request.
Environment variables have been set ‘aud’ and ‘iss’. iss should be `https://sts.windows.net/<TenantID>` and aud should be the API URI you set for your API application in Windows Azure.
The Token is then decoded using the JWT gem, as part of this the rsa_key, iss and aud are checked to ensure it is a token that has been issued by Microsoft and if for your application.
3. Create a new strategy for warden within `lib/strategies/azure_ad_json_web_token_strategy.rb`
This uses the standard warden setup for a strategy, within the authenticate! method in this example we are checking that we have valid claims from Azure AD. You might want to check that the user also exists in your application at this point, or create a new record for them in a User model.
4. Add the Warden middleware to your application by adding the following to your `config/application.rb`
5. Register your strategy with Warden. Create a new file called `initializers/warden.rb`
6. Create a file called `app/controllers/concerns/warden_helper.rb`
This will ensure all methods within your application are authenticated and provides a current_user object that can be used to get information about the user making the API request.
Include the helper within your ApplicationController `include WardenHelper`
7. That completes the setup of the Rails application. Currently if you call the API without being authenticated your application with throw a Warden Authentication exception. You can however register a controller that will be called for Unauthenticated requests and then return the correct 401 status and a relevant JSON object.
Angular JS
In the second part of this we will look at how you can setup an AngularJS application to talk to this API.
