How to: Use an Error URL for Custom Error Handling

Updated: June 19, 2015

Applies To: Azure

Applies To

• Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS)

Summary

This topic explains how to use the Error URL feature to implement custom login error handling in a relying party application. An Error URL allows you to send errors that ACS generates back to the relying party application so the application can log and respond to errors. For example, ASP.NET web sites can use the Error URL feature to present error messages to end users that are branded with the same look and feel as the website.

Contents

• Objectives

• Overview

• Summary of Steps

• Step 1 – Enable the Error URL Feature

• Step 2 – Create the Error Helper Classes

• Step 3 – Process a JSON-Encoded Error Message

• Step 4 – Configure Anonymous Access to the Error Page

• Step 5 – Test Your Work

Objectives

• Identify the required configuration for using the Error URL feature.

• Identify the helper code required to process error messages from ACS.

• Identify and troubleshoot potential pitfalls.

Overview

An Error URL specifies the web address to which ACS redirects users if an error occurs during the login process. The Error URL target is typically a custom error page that is hosted by the relying party application. As part of the redirect, ACS returns information about the error to the relying party application as a JSON-encoded HTTP URL parameter. You can include the JSON-encoded error information in the custom error page and/or display static help text. The following is a sample of a JSON-encoded error message.

{"context":null,"httpReturnCode":401,"identityProvider":"Google","timeStamp":"2010-12-17 21:01:36Z","traceId":"16bba464-03b9-48c6-a248-9d16747b1515","errors":[{"errorCode":"ACS30000","errorMessage":"There was an error processing an OpenID sign-in response."},{"errorCode":"ACS50019","errorMessage":"Sign-in was canceled by the user."}]}

Summary of Steps

Use the follow process to handle ACS error messages:

• Step 1 – Enable the Error URL Feature

• Step 2 – Create the Error Helper Classes

• Step 3 – Process a JSON-Encoded Error Message

• Step 4 – Configure Anonymous Access to the Error Page

• Step 5 – Test Your Work

Step 1 – Enable the Error URL Feature

To enable the Error URL feature for your relying party

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)

3. Click Relying party applications and select a relying party application.

4. On the Edit Relying Party Application page, enter your error page URL in the Error URL field.

   ACS redirects user to this page when login errors occur. Also, ACS sends JSON URL encoded parameters to this page that include the error details.

Step 2 – Create Error Helper Classes

This step creates error helper classes that deserialize the JSON-encoded error messages.

To create Error helper classes

1. Add a class file to your web application and give it a name, such as Error.cs.

2. Implement the Error class as follows.

   public class Error
   {
       public string errorCode { get; set; }
       public string errorMessage { get; set; }
   }
   

   Add another class file and give it a name, such as ErrorDetails.cs.

3. Implement the ErrorDetails class as follows.

   public class ErrorDetails
   {
       public string context { get; set; }
       public int httpReturnCode { get; set; }
       public string identityProvider { get; set; }
       public Error[] errors { get; set; }
   }
   

These classes will be used in the next step when processing error messages from ACS.

Step 3 – Process a JSON-Encoded Error Message

This step shows how to process JSON-encoded error messages that ACS generates.

To process a JSON-encoded error message generated by ACS

1. Add an ASPX web page to your ASP.NET application and give it a name, such as ErrorPage.aspx.

2. Add the following labels controls to the ASP.NET markup.

   <asp:Label ID="lblIdntityProvider" runat="server"></asp:Label> 
   <asp:Label ID="lblErrorMessage" runat="server"></asp:Label> 
   

3. Switch to the page’s code-behind file, ErrorPge.aspx.cs.

4. Add the following declaration to the top.

   using System.Web.Script.Serialization;
   

5. Add the following code to the Page_Load method.

   JavaScriptSerializer serializer = new JavaScriptSerializer(); ErrorDetails error = serializer.Deserialize<ErrorDetails>( 
   
   
                                        Request["ErrorDetails"] ); lblErrorMessage.Text = string.Join("<br/>", 
                                       error.errors.Select(er => string.Format("Error Code {0}: {1}", 
                                       er.errorCode, er.errorMessage)).ToArray());
   
   

   This code processes JSON-encoded error messages from ACS.

Step 4 – Configure Anonymous Access to the Error Page

This step configures anonymous access to the ErrorPage.aspx file. If the page is protected and requires authorization, an infinite redirection loop results. If this occurs when ACS tries to access the page, ACS sends a JSON-encoded error.

To configure anonymous access to the error page

• Open the web.config in your application and add the following entry.

  <location path="ErrorPage.aspx">
    <system.web>
      <authorization>
        <allow users="*" />
      </authorization>
    </system.web>
  </location>
  

  This ensures that access to your page does not cause an infinite redirection loop.

Step 5 – Test Your Work

This step tests your Error URL configuration and implementation.

To enable the Error URL feature for your relying party

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)

3. Click Rule Groups and then click a rule group that is associated with the relying party application.

4. Warning

   The following step cannot be undone. However, if you are deleting generated rules, they can be generated again easily.

5. On the Edit Rule Group page, select all of the rules in the Rules section, and then click Delete Selected Rules.

6. Click Save.

7. Return to your website and navigate to one of the pages using your browser.

8. You should be redirected to your identity provider for authentication—Windows Live ID (Microsoft account), Google, Facebook, Yahoo!, or —whatever is configured for your relying party as the identity provider.

9. After successful authentication you should be redirected back to ACS, which should generate an error since no rules are defined.

10. This error should be displayed on your error page that you created in Step 2 – Create Error Helper Classes, and will be similar to the following:

    uri:WindowsLiveID Error Code ACS50000: There was an error issuing a token.

Another way to test this is to deny user consent. This is presented when you log on using Facebook or Google.