Windows Azure AppFabric Access Control Service (ACS) v2– Returning Friendly Error Messages Using Error URL Feature

Windows Azure AppFabric Access Control Service (ACS) v2 has a feature called Error URL that allows a web site to display friendly message in case of error during the authentication/federation process. For example, during the authentication with Facebook or Google a user asked for consent after successful authentication. If the user denies ACS generates an error that could be presneted to a user in a friendly manner. Another case is when there is a mis-configuration at ACS level, for example, no rules generated for specific identity provider which results in error generated by ACS.

How to show friendly error message for these cases, branded with the look an feel as the rest of my website?

The solution is using Error URL feature available through ACS management portal. ACS generated JSON encoded error message and passes it to your error page. You need to specify the URL of the error page on ACS management portal so that ACS will know where to pass the information. Your error page should pars the JSON encoded error message and render appropriate HTML for the end user. Here is a sample 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 cancelled by the user."}]}

Summary of steps:

To process error messages from ACS complete these steps:

Step 1 – Enable Error URL Feature
Step 2 – Create Error Helper Classes
Step 3 – Process JSON Encoded Error Message
Step 4 – Configure Anonymous Access To The Error Page
Step 5 – Test Your Work

Step 1 – Enable Error URL Feature

To enable Error URL feature for your relying party:

Login to http://portal.appfabriclabs.com.
On the My Projects page click on your project.
On the Project:<<YourProject>> page click on Access Control link for desired namespace.
On the Access Control Settings: <<YourNamespace>> page click on Manage Access Control link.
On the Access Control Service page click on Relying Party Applications link.
On the Relying Party Applications page click on your relying party application.
On the Edit Relying Party application page notice Error URL field in Relying Party Application Details section.
Inter your error page URL. This is the page that will receive JSON URL encoded parameters that include the error details.

Step 2 – Create Error Helper Classes

This step helps creating Error helpers classes for deserializing JSON encoded error messages.

To create Error Helper Classes:

Add class file and give it a name, for example, Error.cs.

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, for example, ErrorDetails.cs.

Implement the ErrorDetials 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 JSON Encoded Error Message

To process JSON encoded error message generated by ACS:

Add an aspx web page to your ASP.NET application. And give it a name, for example, ErrorPage.aspx. It will serve as an error page that will process the JSON encoded error message sent from ACS.

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>

Switch to the page’s code behind file, ErrorPge.aspx.cs.
Add the following declaration to the top:
```
using System.Web.Script.Serialization;
```

Add the following code to Page_Load method:

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

The above code is responsible for processing JSON encoded error messages received from ACS. You might want to loop through the errors array as it might have additional more fine grained error information.

Step 4 – Configure Anonymous Access To The Error Page

To configure anonymous access to the error page:

Open web.config of your application and add the following entry:

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

This will make sure you are not get into infinite redirection loop.

Step 5 – Test Your Work

To test Error URL feature:

Login to http://portal.appfabriclabs.com.
On the My Projects page click on your project.
On the Project:<<YourProject>> page click on Access Control link for desired namespace.
On the Access Control Settings: <<YourNamespace>> page click on Manage Access Control link.
On the Access Control Service page click on Rule Groups link.
On the Rule Groups page click on the rule group related to your relying party.
WARNING: This step cannot be undone. If you are deleting generated rules they can be easily generated once more. On the Edit Rule Group page delete all rules. To delete all rules check all rules in the Rules section and click Delete Selected Rules link.
Click Save button.
Return to your web site and navigate to one of the pages using browser.
You should be redirected to your identity provider for authentication – Windows LiveID, Google, Facebook, Yahoo!, or ADFS 2.0 – whatever is configured for your relying party as identity provider.
After successful authentication your should be redirected back to ACS which should generate an error since no rules defined.
This error should be displayed on your error page that you created in step 2, similar to the following: