How to Authenticate using Azure Active Directory

DreamFactory’s Azure AD connector makes it easy to use an Azure Active Directory tenant for API authentication. By using Azure AD Application Roles it is also possible to assign Users and Groups to DreamFactory roles from the Azure Portal. In this example, we will show how to quickly configure DreamFactory with the proper metadata from Microsoft Azure Active Directory (Azure AD).

Azure AD is built on top of the OAuth2 protocol which defines several methods of authentication that ultimately end with users obtaining an access token for authenticating against a given resource.

In this workflow, users will be redirected from the DreamFactory application to their Microsoft Azure login screen. There, individuals will be prompted to enter an email and password before gaining access to the application resource. Let’s begin by creating a new application within the Azure Active Directory.

Step 1. Register applications in Azure Active Directory

To configure OAuth 2.0 authentication using the client credentials grant type, you need to register both the web service and the client applications in Azure Active Directory. To learn how to do this, see the Microsoft documentation.

Step 2. Configure a client application

A client application is an application that requests a protected resource. After you register it in Azure Active Directory, you need to perform the following steps to apply the client credentials grant type:

1. Open the Azure Active Directory(REF) service. Under, App registrations, open the registration of your client application.

Copy the Application (client) ID to someplace. You will need it to link the client to the web service and to configure the request authentication:

1. In the Client Credentials Grant type, you will need a client secret. To retrieve it, open the Certificates & secrets page and click New client secret:
   
   Add a short description and click Add.
   
   
   
2. Copy the generated value to someplace:
   You will not be able to get the client’s secret after you leave the Certificates & secrets page.
   
   
3. Select Expose an API and set the Application ID URI with the default value. Record this value for later. Select the Add a scope button to display the Add a scope page. Then create a new scope that's supported by the API (for example, Files.Read).
   
   To authorize the client application, click Add a client application and specify the Application ID. Authorizing a client application indicates that this API trusts the application and users should not be asked to consent when the client calls this API.
   
   
   
   
   
4. The last step is to navigate to the Authentication section and set the callback URL. The call back/redirect URL is the page where the user will be redirected to after a successfully authenticated call. In our case, we are pointing to our DreamFactory instance homepage
   
   

Configuring DreamFactory

After completing the application provisioning within Azure AD, you can now complete the configuration with DreamFactory. Using the metadata from your Azure AD instance as a reference, proceed with setting up the Azure Active Directory OAuth connector by clicking on the DreamFactory Services tab, navigating to the OAuth service type, and then selecting the Azure Active Directory OAuth connector.

1. Create an Azure Active Directory OAuth service
   
   
   
   
2. Enter the basic information for the app in the first tab, including the API namespace, label, and description.
3. Enter the configuration for the app based on the information you have from your Azure portal.
   Client ID – String. Required. A public string used by the service to identify your app and to build authorization URLs.

Client Secret – String. Required. A private string is used by the service to authenticate the identity of the application.

Redirect URL – String. Required. The location the user will be redirected to after a successful login.

Icon Class – String. Optional. The icon to display for this OAuth service.

Tenant ID  -- String. Required. Found in the overview section of the Azure Application

Resource -- String. Required. Enter https://graph.windows.net/ 

The DreamFactory Redirect URL

In the above screenshot, we identified the redirect URL as https://demo.dreamfactory/oauth.php. This is a live script that will dump the contents of the DreamFactory JWT. Here is the oauth.php code (download the code from https://gist.github.com/wjgilmore/011f11455b62f35bfefbcfb0b7d8d143). You can use this script as an example to confirm your connector is properly configured because if login is successful this script will dump the session token to the browser window.

 01 <?php

 02

 03 $qs = $_SERVER['QUERY_STRING'];

 04

 05 $domain = 'https://demo.dreamfactory.com/';

 06

 07 # Create a connection

 08 $url = $domain . '/api/v2/user/session?oauth_callback=true&'

 09 . $qs;

 10 $ch = curl_init($url);

 11

 12 # Setting our options

 13 curl_setopt($ch, CURLOPT_POST, 1);

 14 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

 15

 16 # Get the response

 17 $response = curl_exec($ch);

 18 curl_close($ch);

 19

 20 var_dump(json_decode($response));

Let’s review this code:

• Line 03 retrieves the query parameters returned from Azure AD OAuth (code, session, session_state). 
• Line 05 defines the domain or IP address of your DreamFactory installation.
• Line 08 defines the callback URL. When the Azure AD OAuth parameters are sent back to DreamFactory, DreamFactory will return the JWT.
• Lines 10-18 are just standard cURL commands, used to send a request to the designated URL and receive the response.
• Line 20 dumps the JWT

Of course, in a real-world situation, you wouldn’t dump the JWT. Instead, you would parse the response object and pass the session_token value back using the X-DreamFactory-Session-Token header. DreamFactory will check the validity of the token and if it has expired will disallow the request.

Conclusion:

Now you should be finished! Log in to your instance and test it out. If you have any comments or concerns about our code or the steps to reproduce it, feel free to reach out to us at code AT dreamfactory.com with your thoughts!

Additional Resources

• https://docs.microsoft.com/en-us/connectors/custom-connectors/azure-active-directory-authentication
• https://ngrok.com/docs
• https://wiki.dreamfactory.com/DreamFactory/Tutorials/Using_OAuth