iOS Quickstart

Usage

The login control for iOS consists of a UIViewController that handles the entire login process. All you have to do is instantiate the AccessControlSignInViewController with the correct input parameters, present it as a modal view and handle the events fired by the sign in control.

You'll need to include a reference to TheFactorM.Federation.dll in your project. The Federation library has a dependency on JSON.NET, so make sure that you also have this included. Next, for accessing the classes in the library, include the following namespace:

using TheFactorM.Federation;

The following example code shows how you can use the sign in controller.

public void Login()
{
    // Shared login view
    var ctl = new AccessControlServiceSignInController( ... ); 

    ctl.SignInCookieReceived += HandleSignInCookieReceived;

    NavigationController.PresentViewController(ctl, true, null);
}

void HandleSignInCookieReceived (object sender, SignInCookieReceivedEventArgs e)
{
    // For example: set an application wide flag to indicate that the user has signed in
    // or start a webservice call to the application web service to discover the user's identity
    // and/or fetch their data
}

The AccessControlSignInViewController constructor requires five input parameters. It needs the following input:
  • acsNamespace: the namespace of your ACS instance. For example, if your ACS instance is at https://myinstance.accesscontrol.windows.net, the acsNamespace parameter should be "myinstance".
  • homeRealm: the home realm url of your relying party (RP) web application. E.g. "http://www.mycloudapplication.net"
  • replyToAddress: the url of the page to which ACS will redirect the user after authenticating and issueing the security token. This must be the page on your web application that sends the FedAuth cookies to your application. E.g. "http://mycloudapplication.net/login.aspx"
  • cookieDomainUri: the uri on which the cookies, issued by the web application, will be scoped. This is usually the same as the homeRealm url
  • container: a CookieContainer into which the AccessControlSignInController will register the FedAuth cookies issued by the relying party web application. Use the same CookieContainer instance that you will use to do all of your service requests against the web application.

If the SignInCookieReceived event fires, you can be sure that the FedAuth cookies are stored in the CookieContainer you passed to the AccessControlSignInController constructor.

Also, the cookies will be persisted on disk in IsolatedStorage, so you an use them in later application sessions. This way, the user only has to log in when the cookies have expired. The cookies will be valid for the amount of time configured in the relying party web application.

In order to check whether the cookies are still valid, and whether you need to show the user a login view, use the static ReadCookies method on the TheFactorM.Federation.FedAuthCookieUtility class:

bool stillValid = FedAuthCookieUtility.ReadCookies(myGlobalCookieContainer, 
                                                    new Uri("http://cookiedomain"));
if (!stillValid) {
    // show the login screen
}

If ReadCookies returns true, the cookies are still valid for use, and the cookies will be in the CookieContainer instance you passed to this method.

Customization

The AccessControlSignInController will have a white background and uses a text only list of Identity Providers. The Azure ACS can also use logo images for identity providers. If you want to show these images instead of their names, set the UseIdentityProviderImages property accordingly:

ctl.UseIdentityProviderImages = true;

Since it is just a regular UIViewController, you can customize its appearance by manipulating its UIView hierarchy. The AccessControlSignInController has a transparent view itself, so you can insert a nice background image into it for your own branding. For example:

// have it flip over when showing the login screen
ctl.ModalTransitionStyle = UIModalTransitionStyle.FlipHorizontal;

// custom branding by inserting a background view
var background = new UIImageView(new RectangleF(0, 0, 320, 568));
background.Image = UIImage.FromBundle("MyBackground.png");
ctl.View.InsertSubview(background, 0);

Last edited May 18, 2013 at 2:19 PM by roy_cornelissen, version 6

Comments

No comments yet.