Login Pages and Home Realm Discovery

Updated: June 19, 2015

Applies To: Azure

Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS) provides two easy ways to generate a federated login page for your website or application:

Option 1: ACS-Hosted Login Page

ACS hosts a basic federated login page that can be used in your relying party application. This login page is hosted at the WS-Federation protocol endpoint for your namespace and can be accessed by a URL with the following format.

https://<YourNamespace>.accesscontrol.windows.net/v2/wsfederation?wa=wsignin1.0&wtrealm=<YourAppRealm>&redirect=false

In this URL, replace <YourNamespace> with the name of your Access Control namespace. In addition, this URL requires the following parameters:

• wa—Set to wsignin1.0

• wtrealm—Set to the value of the realm for your relying party application. To find the realm value, in the ACS Management Portal, click Relying party applications, select an application, and see the Realm field.

To find the login page links for your relying party applications:

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 Application integration, click Login pages, and then select a relying party application.

   The Login Page Integration page displays login page options for the application.

The following image shows the default login page for an application that supports Windows Live ID (Microsoft account), Google, Yahoo!, Facebook, and "Contoso Corp," a fictitious WS-Federation identity provider.

To replace a WS-Federation identify provider button with an e-mail address text box, add e-mail address suffixes to the login page links for your WS-Federation identity provider. This approach is useful when a many WS-Federation identity providers are configured for your relying party application. The following image shows a sample page.

To expedite the integration of ACS with your relying party application, use the default ACS-hosted login page. To customize the layout and appearance of this page, save the default login page as an HTML file and copy the HTML and JavaScript to your application where it can be customized.

Option 2: Host a Custom Login Page as Part of Your Application

To enable full control over the appearance, behavior, and location of your federated login page, ACS provides a JSON-encoded metadata feed with the names, login URLs, images, and e-mail domain names ( only) of your identity providers. This feed is known as the Home Realm Discovery Metadata Feed.

Sample custom login page

To download an sample HTML login page for each of your relying party applications:

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 Application integration, click Login pages and then select a relying party application.

4. On the Login Page Integration page, click Download Example Login Page.

The sample HTML code is identical to the HTML code for the ACS-hosted login page.

This sample includes JavaScript functions for rendering the page. A script tag at the bottom of the page calls the metadata feed. Custom login pages can consume the metadata using pure client-side HTML and JavaScript as shown in this example. The feed can also be consumed and used to render a custom login control in any language that supports JSON encoding.

Home Realm Discovery Metadata Feed

To find the home realm discovery metadata feed URLs for your relying party applications:

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 Application integration, click Login pages, and then select a relying party application.

The URL appears on the Login Page Integration page for the application under Option 2: Host the login page as part of your application.

The following is a sample home realm discovery feed URL.

https://YourNamespace.accesscontrol.windows.net/v2/metadata/IdentityProviders.js?protocol=wsfederation&realm=YourAppRealm&reply_to=YourAppReturnURL&context=&version=1.0&callback=OptionalFunctionName

This URL uses the following parameters:

• YourNamespace—Required. Set to the name of your Azure namespace.

• protocol—Required. This is the protocol that your relying party application uses to communicate with ACS. In ACS this value must be set to wsfederation.

• realm—Required. This is the realm that you specified for your relying party application in the ACS Management Portal.

• version—Required. In ACS this value must be set to 1.0.

• reply_to—Optional. This is the return URL that you specified for your relying party application in the ACS Management Portal. If omitted, the value of the return URL is set to the default value that is configured for your relying party application in the ACS Management Portal.

• context—Optional. This is any additional context that can be passed back to the relying party application in the token. ACS does not recognize these contents.

• callback—Optional. You can set this parameter to the name of a JavaScript function that you want to run when the JSON feed is loaded. The JSON feed string is the argument that is passed to this function.

JSON feed data format

When the metadata feed is requested with valid parameters as previously described, the response is a document containing a JSON-encoded array of arrays, with each internal array representing an identity provider with the following fields:

• Name—The human-readable display name for the identity provider.

• LoginUrl—A constructed login request URL.

• LogoutUrl—This URL allows end users to sign out of the identity provider they signed in with. This is currently only supported for and Windows Live ID (Microsoft account) and is empty for other identity providers.

• ImageUrl—The image to display, as configured in the ACS Management Portal. Blank if there is no image.

• EmailAddressSuffixes—An array of email address suffixes associated with the identity provider. In ACS, email address suffixes can only be configured for identity providers via the ACS Management Portal. Returns an empty array if there are no suffixes configured.

The following example shows the JSON feed when Windows Live ID and AD FS 2.0 are configured for the relying party application. The user has set an image URL for Windows Live ID in the ACS Management Portal and added an e-mail domain suffix for the identity provider.

[ {
   "Name":"Windows Live ID",
   "LoginUrl":" https://...",
   "LogoutUrl":" https://...",
   "ImageUrl":"https://...",
   "EmailAddressSuffixes":[]
},
{
   "Name":"My ADFS 2.0 Provider",
   "LoginUrl":" https://...",
   "LogoutUrl":" https://...",
   "ImageUrl":"",
   "EmailAddressSuffixes":[“contoso.com”]
} ]

See Also

Concepts

ACS 2.0 Components