This project is read-only.

Configuring Azure Active Directory for GeRes2

Setting-up Azure Active Directory is fairly easy, as well, although it involves a bit more steps as compared to setting up Storage and Service Bus for GeRes2. Before getting into the details of the setup, please note that you can easily change how you secure GeRes2, since the JobHub WebAPI and SignalR pieces are based ASP.NET OWIN and do not involve any special or custom implementations.

That said, if you want to authenticate against a different OAuth provider or use a completely different mechanism, change the Startup\ConfigAuth.cs code file in the project GeRes.Azure.PaaS.JobHub project.

To stick with Azure Active Directory for Authentication, you need to setup the GeRes JobHub as a registered application and have at least one application that represents your client applications as part of the Azure Active Directory configuration. Perform the following steps to completely configure authentication and basic authorization (unfortunately at the time of writing this documentation, not all operations where possible to be completed through the management portal):

  1. Sign in into the Microsoft Azure Management portalMicrosoft Azure Management portal and navigate to the “Active Directory” section.
    image
  2. Create a new directory if you don’t have one or don’t want to use your existing directory. Since the authentication into the Azure management portal is implemented with Azure AD, as well, every subscription should have a directory. For your dev/test purposes you can use that one, for customer projects you should consider creating separate directories or directory tenants as per the Azure AD documentation.
  3. Open up the directory in which you want to manage the GeRes2 security and authorization and navigate to the “Applications” tab inside of the directory management portal as shown below.
    image
  4. Create a new application for the GeRes2 JobHub. You can freely select names and URIs as per your naming conventions. The choices for those below made as part of this documentation are just examples.
    1. Click the “Add”-button in the bottom-command line of the directory.
    2. Then select “Add an application my organization is developing” in the popup.
      image
    3. Pick any name you want for that application, e.g. GeRes2 Job Hub. Especially select the option “Web Application and/or Web API” from the options below.
      image
    4. Specify a sign-on URL and an App ID URI. The sign-on URL is not relevant since we don’t do interactive browser logins in GeRes2. The App ID URI is relevant and can be any valid URI (it does not need to be a physical URL!!). Copy this App ID URI for later reference since we need to update the GeRes2 configuration and the client configuration with it!
      image
  5. Create a new application that represents valid client applications for the GeRes2 JobHub. Note: you don’t need to create new applications in Azure AD for each consuming client if you just re-use the secret key configured as part of this configuration across multiple client applications. For different customers, of course, you should create client applications for each so that every customer gets a different client ID and secret for authenticating against the GeRes2 JobHub.
    1. Again, click the “Add”-button in the bottom-command line of the directory.
    2. Again, select “Add an application my organization is developing” in the popup.
      image
    3. Now select an appropriate name for the permitted client application (or group of client applications). Also let the type of the application be a “Web Application and/or Web API” since we use service credentials instead of end-user credentials for authentication.
      image
    4. In the next step, for Sign-On URL and APP ID URI select any valid URI. These settings are not relevant except for this context and won’t be used by GeRes2. Of course if you want to make use of them otherwise, configure them appropriately.
    5. After the application entry has been created in Azure AD, navigate to the “Configure”-tab as shown below:
      image
    6. Scroll down until you see the settings for “CLIENT ID” and a section named “keys”.
      image
    7. Copy the ClientID since you need it in your GeRes2 client application (e.g. the GeresJobRequestorSampleConsole sample project included in the GeRes2 solution).
    8. Next you need to create a secret key used for the authentication of clients represented by this entry in Azure AD. For this purpose, in the keys selection select a duration in the drop-down list and then hit save in the bottom toolbar of the portal. This generates a secret key which can be used by clients together with the client id you copied as part of step 7 for authentication. In other words – it is a valid service credential.
      image
      image
      image
      Note: copy the secret key immediately since you won’t be able to retrieve it anymore after the first page refresh in the Azure management portal.
  6. Now that you have configured applications for both, the GeRes2 JobHub and client applications using a specific Client ID and secret key with the previous two steps, you need to add a permission that allows the applications with a specific Client ID to call the GeRes2 JobHub. Unfortunately the Azure Management portal did not offer a way to configure these permissions at the time when this documentation was created. Therefore you need to configure the permission either programmatically through the Azure AD Graph API or use a free sample-tool available from Microsoft called the Graph Explorer. We use the Graph Explorer as part of this tutorial.
    1. Important: for the graph explorer to work best, start with creating a new user in the User’s section of your Azure Active Directory which is a Global Administrator!! Use this Global Administrator user to sign-in into the Graph Explorer!
    2. Navigate to https://graphexplorer.cloudapp.net/ and sign-in using the button on the top right with a global administrator user of the Azure AD (see step 1 above).
      image
    3. Next click the “Add Application Permission” link in the top right section of the Graph Explorer. This will open up a UI that allows you to add a permission for the application created in step 5 above to call the GeRes JobHub application created in step 4 above.
      image
      After clicking “Create Permission” the following screen will be displayed. The client id displayed there is exactly the same as the one in the Azure Management portal before. Note: don’t get distracted if the Credential Key field says, that no key has been generated. This is because existing key cannot be retrieved either and we will make use of the key generated before in step 5.8 earlier.
      image
  7. As a next step we will need to update the GeRes2 Service Configuration. Open the appropriate *.cscfg configuration file (by default we only ship with ServiceConfiguration.Local.cscfg for local debugging – but you need to configure the Azure AD settings there as well). There are two settings for the web role Geres.Azure.PaaS.JobHub which you need to update:
    1. Geres.Security.AzureAdTenant
      to match you Azure Active Directory tenant (<yourtenantname>.onmicrosoft.com)
    2. Geres.Security.AzureAdAudienceUri
      to match the APP ID URI you have configured in Azure AD for the GeRes Job hub application in step 4.
      image
  8. (optional) Finally if you want to test or debug your GeRes2 deployment using the included GeresJobRequestorSampleConsole, you need to configure the Azure AD tenant as well as the client ID and client secret there. The GeRes2 client SDK uses the Active Directory Authentication Library NuGet package to then authenticate against Azure AD using the client ID and the secret key as defined per steps 5.7 and 5.8 earlier.
    1. Open the app.config file in the project GeresJobRequestorSampleConsole of the GeRes2 solution.
    2. In the <appSettings> configuration section, update the following settings:
      image
    3. WindowsAzureADTenant – replace the substring “yourgeresadtenant” with the name of your Azure AD tenant.
    4. ClientId – replace the value with the client ID copied in step 5.7 earlier.
    5. ClientSecret – replace the value with the secret key generated and copied in step 5.8 earlier.
    6. WindowsAzureAdGeresWebApiId – replace the value with the APP ID URI selected in step 4.4 earlier.

Note: the client id and the client secret are used in  the GeresJobRequestorSampleConsole to authenticate against Azure AD using the GeRes2 client SDK libraries included in the folder sdkclient of the GeRes2.sln solution. The project GeRes.ClientSdk.Core is a portable library which contains the base class implementation for all possible client libraries including .NET, Windows 8 and Windows Phone 8.

As part of this release we included a client SDK for full-fledged .NET applications, only, since that was the primary requirements of the partners we’ve been working with on this project. This is encapsulated in the Geres.ClientSdk.NetFx project. In future releases we might add an additional client SDK libraries such as one for Windows 8 store apps or Windows Phone apps, for example.

After you have configured Azure AD for GeRes2 and updated the configuration files appropriately, you should configure Service Bus and Storage for GeRes2 if you have not done so, yet. For further reference look at:

Configuring Storage for GeRes2

Configuring Service Bus for Geres2

Last edited May 1, 2014 at 12:27 PM by mszcool, version 4