Introduction

Microsoft Azure is a cloud computing service. Customers can use Azure to build, test, distribute, and manage applications online. Among the several hundred features offered as part of Azure is a Single Sign On utility, accessed through Windows Active Directory. Datalogics is pleased to support Microsoft Azure as a Single Sign-On provider for READynamic.

Active Directory is a Microsoft utility that manages credentials and permissions for a network. When a user logs on to a network, Active Directory confirms that the user’s account name and password is valid. Azure extends Active Directory to include the ability to provide users with the ability to access all of the applications and services within a Windows network with single account name and password.
Azure users create tenants to organize features and services for their users. It is possible to create more than one tenant in Azure to structure your environment, each with its own set of services and applications. For example, if you represent a publishing firm, you can create separate tenants in Azure for your fiction and non-fiction publishing systems. Or you can set up a separate Azure tenant to serve systems and users in your educational publishing division, a second tenant for your retail division, and a third for your business publishing division.

You may have in place an account with Azure, and your own tenant or tenants. In fact, you may already be using Azure to provide Single Sign-On services to your users, and so you might already have a set of Azure applications that you set up to allow your users to log on to other systems. In this event, setting up READynamic to work with Azure as a Single Sign-On provider should be easy if you already have an Azure account in place.

We take you through the steps involved so that it will also be easy if you are new to Azure.

NOTE: Sometimes, when a Mac user working with the Chrome browser logs on to READynamic using the Azure Single Sign-On client, that user is sent back to the same login screen instead of to the READynamic Portal.

This rarely happens, and is easy to correct. The user should simply refresh the browser window and the appropriate screen should appear.

Setting up Your Azure Environment

1. To configure OAuth2 to work with Azure, start by visiting the Azure developer’s site, and create an account there:

https://azure.microsoft.com/en-us/free/

2. Log on to your Azure account.

When you log on, you will see the Dashboard Screen.

If you already have a tenant in place that you can use with Azure, go to Creating a READynamic Application in Azure.

Creating a Tenant

1. If you need to create a new tenant, click:

2. Enter Azure AD B2C in the search field on the top of the screen:

3. Select Azure AD B2C:

4. Click . Click the option shown below:

5. Complete the entry screen that appears.

6. Complete the fields and click .

Creating a READynamic Application in Azure

1. From the Dashboard, click  to open the All Services Screen.
2. Select “Azure AD B2C.” Azure AD B2C refers to Azure Active Directory Business to Consumer.

Take care not to confuse Azure AD B2C with Azure Active Directory. Those are in fact two completely different services; to use Azure with Single Sign-On, you need Azure AD B2C.

3. Scroll down on the All Services Screen to the section called “Identity,” or in the Filter box on the top of the screen, type in “Azure AD B2C” to search for this service.

4. Make Azure AD B2C a favorite. Click the star , so that it changes color, . If you make this service a favorite, a new tab appears on the screen on the left side of the screen, at the bottom of the tool bar:

5. Click Azure AD B2C. The Azure AD B2C window opens.

Building the Application

1. Click.

A blank Applications Screen appears.

2. Click to create a new application.

The New Application Window appears.

3. Enter the name of the application.
4. Click Yes for Web App, and enter a Reply URL.

When you create the application, enter a valid URL for the return address. After a user attempts to log on to READynamic using Azure Single Sign-On, Azure will send an authentication response to the Reply URL.  This response will either be a token showing that the user is permitted to log on, or an error message. Azure directs the client to this web address for log on requests to READynamic.

Commonly, for READynamic the Reply URL is based on the URL for your customer portal.  Your portal might look something like this:

https://boxcollege.readynamic.com

For use with Azure, you need to add an Azure callback statement to the end of this web address.

/auth/azure_active_directory_b2c/callback

With this syntax:

https://<portal address>/auth/azure_active_directory_b2c/callback

So the Reply URL should look something like this:

https://boxcollege.readynamic.com/auth/azure_active_directory_b2c/callback

You will need to add this value as a setting in the configuration file, omniauth_overrides.yml.

Make sure that this web address is formatted properly.  It must start with "https://"

5. When you enter a valid address, the Create button is activated. Note that you cannot create an application in your Azure account if the Reply URL is not valid.

6. Click .

You will see a message that the application was successfully created.

The new application appears on the Applications screen.

7. Click the name of the application. The Properties window appears.

Working with the Application Key in Azure

1. Next, you need to generate a key. Click :

2. Click .

3. Click . A message appears stating that the application was updated. The key appears on the Key Screen.

Applying the Key

Note that Azure generates this key as a random string of 24 alphanumeric and special characters.

It should look something like this:

Qu*j6TE09)7-QbK3p=zEk4r

You need to copy this key into a configuration file provided with the READynamic software distribution package. The software reads the key from that file parameter.

But some kinds of characters can cause problems when READynamic interprets the key value. Consider this example:

f!"3zCvxv9&ux2p^5qa3B26~

Note the double quotes character:

f!"3zCvxv9&ux2p^5qa3B26~

In text streams many applications interpret a quotation mark, single or double, as the beginning or end of a literal value. If READynamic finds a quote character in a key, it will look for a second quote character to match and will end up rejecting the key if it can’t find it. If in fact a second quote appears, READynamic will only read the characters within the quotes, not the entire key.

Likewise, if a greater than or less than symbol appears (">" or "<") READynamic will interpret this as the beginning or end of an HTML tag marker, like "<p>" or "</b>." The system will look for a pair of HTML elements and reject the key as undecipherable.

If Azure generates a key for your application and it includes any of these random characters, READynamic will not be able to read it, and your Azure Single Sign-On configuration will not work:

"	Double quote
'	Single quote
`	Back quote, or grave accent
<	Less than symbol
>	Greater than symbol

This issue is very easy to fix. Simply generate new keys for an application in Azure until you find one without any of these characters. Then, apply that key to READynamic.

Click, and then click .

Up to two keys will appear on Application Keys Screen at a time. If a key has one of these excluded characters right click on the value and click Delete to delete it. It only takes a few seconds to create or delete a key, so you should be able to quickly find one that you can use.

Adding a Policy

Next, create a policy for the application. The policy describes what the user needs to provide to access READynamic through Azure, and what READynamic is looking for from a user who signs in.

1. Return to the Applications screen.

2. Under POLICIES on the left side of the screen, click .
3. Click to create a new policy.

4. Enter a name for the policy. For our example we use "readynamic."
5. Complete the rest of the screen and click .
6. Return to the Applications Screen.

Adding a Scope

1. From the Applications Screen, select the application.
2. Click .

3. Complete the blank fields that appear on this screen to add a new scope.  Enter "read" for SCOPE and "any" for DESCRIPTION. When you click Save the full scope value fills in automatically. Your scope will appear in the Full Scope Value field. You will need to copy this scope value to the omniautgh_overrides.yml configuration file. We describe this below.
4. Click .
5. Click to add an API access to your scope.

6. For the Select API field, click the arrow and select your application.
7. For the Select Scopes field, select all scopes.
8. Click OK.

Configuring READynamic to work with your Azure application

At this point, you have everything you need to link your READynamic environment to Azure Single Sign-On.  In creating the Application in Azure, Azure generated four values that you need to copy into a pair of YML configuration files that we provide with your READynamic software installation package.  All of these values appear on the Azure Application Page.

Click Properties:

This screen provides:

A) Application ID
B) Reply URL
C) Tenant ID

Disregard the reference to the App ID URI. The tenant ID value is underlined on the above screen.

Then, click the Keys tab to display the key value:

This is an example of the policy name value:

And this screen shows the name of the scope:

	Azure Application Page Value	omniauth_overrides.yml file	Description
A	Application ID	application_id	The Application ID is a unique code that represents your READynamic application in login requests to Azure AD B2C.
B	Reply URL	redirect_uri	Azure AD B2C directs users logging on to READynamic back to this web address.
C	Tenant ID	tenant_id	The tenant ID defines your Azure environment. You might use a variety of different services provided by Azure, even within Azure AD B2C you might have five or six different applications. Besides providing SSO service for READynamic, you might also provide Single Sign-On for a cloud based backup utility, or an inventory system. These services and features are all a part of your Azure Tenant. The Tenant ID should always be in the form “xxx.onmicrosoft.com.”
D	App Key	key	The secret is a unique code that identifies your application to Microsoft, for use with Azure. Think of the Application ID as your account name, and the key as the password.
E	Policy	policy_name	The policy describes what a user must provide when creating an account (sign up) to access the system, READynamic, and what READynamic looks for when a user seeks to sign in. For the purposes of READynamic, this will be a display name and the user's electronic mail address.
F	Full Scope Name	scope	The scope defines the sets of permissions that govern what rights users have to access data after logging on to the system. In the case of READynamic, we have you set up the scope as full rights to read any data provided through the system.

For each of these four values, right click on the value to select it, and then copy and paste it into the configuration file called omniauth_overrides.YML.

omniauth_overrides.yml

You will find the Azure OAuth2 settings near the beginning of the omniauth_overrides.yml file.

# Azure OAuth2 strategy, uses the azure-oauth2 gem
azure_active_directory_b2c:
   application_id: application_id
   key: key
   tenant_id: tenant_id
   redirect_uri: https://readynamic.example.com/auth/azure_active_directory_b2c/callback
   policy_name: b2c_1_<policy_name>
   scope: https://<tenant_name>/readynamic/read

When you finish editing the file, it should look something like this:

azure_active_directory_b2c:
   application_id: 6dea8b52-9eef-43c9-ad18-2fbc59929ae2
   key: qPnHu2~p=5zM72.QqPCRk/S8
   tenant_id: boxcollege.onmicrosoft.com/
   redirect_uri: https://boxcollege.readynamic.com/auth/azure_active_directory_b2c/callback
   policy_name: b2c_1_readynamic
   scope: https://boxcollege.onmicrosoft.com/readynamic/read

Make sure that the web address for the redirect_uri starts with “https.”

server_configuration_overrides.yml

You also need to enable Azure in the server_configuration_overrides.YML configuration file.  Look for the login_strategy setting:

# if login_strategy is enabled, portal's home will be redirected to "redirect" path
login_strategy:
   enabled: false
   redirect: /auth/<strategy_name>

Set the enabled value to “true,” and add Azure as the strategy name under redirect, like this:

# if login_strategy is enabled, portal's home will be redirected to "redirect" path
login_strategy:
   enabled: true
   redirect: /auth/azure_active_directory_b2c

Save both YML configuration files and restart your READynamic server.  The next time you log on, you should be asked for your Azure credentials.