Implement an Azure Active Directory

Objective 5.3: Integrate an app with Azure AD

Organizations that develop their own line-of-business (LOB) applications can protect access to those applications using Azure Active Directory. The type of LOB application that can be integrated with Azure Active Directory can vary. It can be a web application that users access using their browser, or a desktop client application that is installed on the user’s computer. It may be a web service lacking a user interface that other LOB applications depend on to provide a complete solution. It could also be an application that has capabilities to create, edit, or even delete objects in the directory.

The process for integrating an application developed in-house requires careful coordination between the IT professional managing the Azure Active Directory, and the application developer responsible for developing the application. The content in this objective draws attention to the skills and knowledge the IT professional needs to integrate these kinds of applications with Azure Active Directory and configure application permissions.

Add a web application or web service

The process of integrating either a web application or web service with Azure Active Directory using the management portal begins the same way. In the Applications page of your directory, click Add at the bottom of the page and choose the option to Add An Application My Organization Is Developing. This action launches a wizard where you can provide a name for the application and also indicate the type of application, as shown in Figure 5-24. The name can be anything you want it to be. Notice that for the application type, web application and web service (also known as web API) are considered one and the same.

After choosing the application type for Web Application And/Or Web API, the second and final page in the wizard prompts you for the application’s sign-on URL and the application ID URI, as shown in Figure 5-25. The sign-on URL is the URL that clients will use to access the application. The application ID URI is a URI that uniquely identifies the application in your Azure Active Directory. The URI can be anything you want as long as it is unique to your directory and a valid URI.

By completing the wizard to add the application you have created only the infrastructure that Azure Active Directory needs to support authenticating users of your application. Beyond the four settings you provided previously for this application, Azure Active Directory has also configured additional settings in your directory that application developers will need to build the application. This is where the careful coordination between the IT professional and application developer begins.

The application developer needs the following settings to develop and configure the application that will be protected by Azure Active Directory.

• Application ID URI The URI that you provided in the Add Application Wizard for the application. The application developer will use this in the code and/or configuration to associate the application with this entry in the directory.
• Reply URL By default, this is the sign-on URL you provided in the Add Application Wizard for the application. When Azure Active Directory issues a security token for a user of the application, it redirects the client back to the application URL so that the token can be presented to the application and validated.
• Application endpoints Endpoints that application developers can reference in the application code and/or configuration that are used to sign in and sign out users of the application.

The first two settings can be retrieved in the Single Sign-On section of the Configure page for the application, as shown in Figure 5-26. To get to the Configure page, click the application in the Applications page, and then click the Configure tab.

The application endpoints can be accessed from the management portal by clicking View Endpoints. The application endpoints are the same for all applications in your Azure Active Directory. However, they are unique to each tenant (or organization) in Azure Active Directory. Azure Active Directory supports the following protocols and makes available application endpoints for each, as shown in Table 5-5.

TABLE 5-5 Protocols and application endpoints supported by Azure Active Directory

Protocol	application endpoints
WS-Federation	https://login.windows.net/<tenant>/wsfed
SAML-P	https://login.windows.net/<tenant>/saml2
OAuth	https://login.windows.net/<tenant>/saml2 https://login.windows.net/<tenant>/oauth2/authorize

The <tenant> in the URL for the application endpoints above is a GUID/ID assigned to your tenant (or organization) in Azure Active Directory and therefore referred to as tenant specific endpoints. Application developers use these application endpoints in code and/or configuration to externalize the authentication of users to Azure Active Directory. Which endpoint is used depends largely on the type of application being developed and the authentication requirements for the application. Figure 5-27 shows all of the application endpoints available for a tenant in Azure Active Directory.

In addition to the application protocol endpoints shown previously in Table 5-2, Azure Active Directory publishes additional tenant-specific endpoints that application developers may require when developing applications protected by Azure Active Directory. These are the federation metadata document and graph API endpoints.

The federation metadata document is an XML document that describes the security token service (STS) that is responsible for issuing SAML tokens to authenticated users. The URL for the STS is unique for each tenant in Azure Active Directory and is of the form https://sts.windows.net/<tenant>. This document also contains the certificate that Azure Active Directory will use to sign the tokens it issues and is one of the primary means by which applications validate tokens that are presented by clients accessing the application. If an application receives a token signed by an issuer other than the one it has externalized authentication to, then it can deny access to the application. The remainder of the federation metadata document describes the application endpoints for the WS-Federation and SAML-P protocols.

You can view the contents of the federation metadata document by opening the endpoint URL in a browser. However, it is more common that application development tools such as Visual Studio consume the metadata document because developers build applications using WS-Federation or SAML-P. The tools in Visual Studio, and other developer tools, take care of the extremely intricate configuration details required for the application to externalize authentication to Azure Active Directory by extracting the necessary information from the federation metadata document.

The graph API endpoint is used by applications to retrieve additional properties of directory objects such as users and security groups. It is also used by applications to create, edit, or even delete directory objects if the application has been configured with permissions to do so. This endpoint will be discussed further in the Configure Graph API permissions for an application section.

Enable access to a web application or web service from other applications

Many applications are architected in a way that allows certain features of the application to evolve and be versioned independently while collectively providing a complete solution for the business. For example, a web application that users interact with in a browser may have a dependency on a set of web services (or web APIs) that are used to send and receive data to a database, or perform business logic for the web application.

For a web service to be accessible from other applications registered in the directory, its application manifest must be updated to allow it. The application manifest is used to configure properties for an application that the management portal does not provide a user interface for. Enabling access to a web service from another application is one example where the application manifest has to be edited and can be done as follows:

1. Go to the Applications page in the management portal.
2. Click the name of the application whose manifest you want to edit.
3. At the bottom of the page, click Manage Manifest, and then select the Download Manifest option.
4. Save the manifest file to your local computer.
5. Edit the file using a text editor such as Notepad.
6. In the management portal, click Manage Manifest, and select the Upload Manifest option.
7. Click the check mark to upload the edited manifest file.

The application manifest is a JSON-formatted file. Listing 5-1 illustrates the default manifest for a web service added to Azure Active Directory.

LISTING 5-1 Application manifest for a web application/web service added to Azure Active Directory

{
  "allowActAsForAllClients": null,
  "appId": "7f12aa02-123f-4599-ad5d-f9851e36ce84",
  "appMetadata": {
    "version": 0,
    "data": []
  },
  "appRoles": [],
  "availableToOtherTenants": false,
  "displayName": "Contoso Support Web Service",
  "errorUrl": null,
  "groupMembershipClaims": null,
  "homepage": "https://contoso.com/support-api",
  "identifierUris": [https://contoso-support-api
    https://contoso-support-api
  ],
  "keyCredentials": [],
  "knownClientApplications": [],
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [],
  "oauth2RequirePostResponse": false,
  "passwordCredentials": [],
  "publicClient": null,
  "replyUrls": [
    https://contoso.com/support-api
  ],
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ],
  "samlMetadataUrl": null,
  "defaultPolicy": [],
  "extensionProperties": [],
  "objectType": "Application",
  "objectId": "1688c779-e30b-4dea-9433-ea71bb44dced",
  "deletionTimestamp": null,
  "createdOnBehalfOf": null,
  "createdObjects": [],
  "manager": null,
  "directReports": [],
  "members": [],
  "memberOf": [],
  "owners": [],
  "ownedObjects": []
}

To allow this application to be accessible from other applications registered in Azure Active Directory requires that the oauth2Permissions node be updated with the property settings to allow access to it. Listing 5-2 illustrates the change to the oauth2Permissions node to allow full-delegated user access to the application.

LISTING 5-2 An abbreviated application manifest with oauth2Permissions added

... abbreviated ...
    "oauth2AllowImplicitFlow": false,
    "oauth2AllowUrlPathMatching": false,
    "oauth2Permissions": [
      {
        "adminConsentDescription": "Allow the app full access to the Contoso Support Web
  API on behalf of the signed-in user",
        "adminConsentDisplayName": "Have full access to the Contoso Support Web API",
        "id": "C39B0282-F0F4-431D-941B-777DC456C962",
        "isEnabled": true,
        "origin": "Application",
        "type": "User",
        "userConsentDescription": "Allow the application full access to the Contoso
  Support Web API on your behalf",
        "userConsentDisplayName": "Full access to Contoso Support Web API",
        "value": "user_impersonation"
      }],
    "oauth2RequirePostResponse": false,
...  abbreviated ...

With this edit in place, another application in Azure Active Directory will be able to see and configure access to this application if needed, which you see in the subsequent section where adding a native application to Azure Active Directory is discussed.

Adding a native application

Integrating a native application with Azure Active Directory using the management portal begins with a similar process to what you learned in the previous section for web applications and web services.

1. Go to the Applications page of your directory.
2. Click Add at the bottom of the page.
3. Choose the option to Add An Application My Organization Is Developing.
4. In the first page of the Add Application Wizard, provide a name for the application and select the option to indicate the application is a Native Client Application.
5. In the second page of the Add Application Wizard, provide a Redirect URI. This is a URI that uniquely identifies the application in your Azure Active Directory. It can be anything you want as long as it is unique to your directory and a valid URI.

As before, by completing the wizard to add a native application you have created the infrastructure that Azure Active Directory needs to authenticate users of your application. For native applications, an application developer needs the following settings to develop and configure the native application that will be protected by Azure Active Directory:

• Redirect URI The URI you provided in the second page of the Add Application Wizard.
• Client ID An identifier that Azure Active Directory generates and is used to identify the native application. Application developers use the Client ID in the application when accessing the graph API or other web APIs registered in Azure Active Directory.

You can get both of these values from the Properties section of the Configure page for the application, as shown in Figure 5-28.

Configure access to other applications

Native applications added to Azure Active Directory use the OAuth application endpoints to acquire an access token for a specified resource such as a web service application registered in the same directory. However, adding the native client application to Azure Active Directory does not mean the application has permissions to access the web service. Additional configuration must be added in Azure Active Directory to allow the native application to access the web service. This configuration is easily added using the management portal.

1. Go to the Applications page of your directory.
2. Click the name of the native application.
3. Click the Configure tab at the top of the page.
4. In the Permissions To Other Applications section, select the application you want to enable access to from the native application in addition to the appropriate permissions.

Figure 5-29 is an example of a native application being configured with permissions to a web service also registered in Azure Active Directory.

Configuring graph API permissions for an application

The graph API is used by applications that need access to read directory objects in Azure Active Directory or to create, update, and delete objects. For example, an application may need to query the directory to determine a user’s manager in the organization or add the user to a particular security group. Azure Active Directory supports these kinds of application requirements, but your application must be configured with the necessary permissions to allow it as this goes beyond the default settings that provide single sign-on support for users.

The graph API is available for both web applications/web services and native applications, and can be configured via application permissions or delegated permissions.

Application permissions may be assigned to access the directory without a user context and are only available for web applications/web services. Delegated permissions are used to access the directory as the user signed in to the application and are available for both web applications/web services and native applications.

Permissions to access the graph API can be added to the configuration for an application using the management portal by selecting either the Read Directory Data or Read And Write Directory Data permission for the Windows Azure Active Directory application. Figure 5-30 illustrates setting the Read And Write Directory Data permission for a web application added to the directory.

Objective summary

• For SaaS applications configured using federation-based single sign-on, users are automatically signed in using their organizational account information in Azure Active Directory.
• For SaaS applications configured using password-based single sign-on, users are automatically signed in using their account information from the application. In this scenario, the user account information is securely stored in Azure Active Directory.
• Azure Active Directory provides application endpoints for WS-Federation, SAML-P, and OAuth 2.0 protocols. Azure Active Directory supports security token formats SAML and JWT.
• The oauth2Permissions array node in a web service application’s manifest can be edited to allow the web service to be accessed from other applications registered in the directory, such as web applications or a native applications.
• The graph API is used by applications to create, read, update, or delete directory objects in Azure Active Directory. An application must be configured for either the Read Directory Data or Read And Write Directory Data permissions to use the graph API.

Objective review

Answer the following questions to test your knowledge of the information in this objective. You can find the answers to these questions and explanations of why each answer choice is correct or incorrect in the “Answers” section at the end of this chapter.

1. Which protocols does Azure Active Directory provide application endpoints for? (Choose all that apply.)

   1. WS-Federation
   2. Federation metadata document
   3. SAML-P
   4. OAuth 2.0

2. Which application setting in Azure Active Directory is used to uniquely identify a web application that has been added to the directory?

   1. Sign-on URL
   2. Reply URL
   3. Application ID URI
   4. Name

3. What is the URL for the security token service (STS) endpoint that issues a SAML token for an authenticated user?

   1. https://sts.windows.net/<tenant>
   2. https://login.windows.net/<tenant>/saml2
   3. https://login.windows.net/<tenant>/wsfed
   4. https://graph.windows.net/<tenant>

4. A developer building a web application for your organization needs the certificate that your Azure Active Directory uses to sign SAML tokens. Which application endpoint should you provide the developer?

   1. WS-Federation sign-on endpoint
   2. SAML-P sign-on endpoint
   3. Graph API endpoint
   4. Federation metadata document endpoint