Login Pages and Home Realm Discovery

You can download an example HTML login page for each of your relying party applications by completing the following steps:

1. Launch the ACS Management Portal. For more information, see ACS Management Portal.
   
   
2. Click Application integration in the tree on the left-hand side under the Development section, and then on the Application Integration page, click the Login pages link.
   
   
3. Click the relying party application for which you want to view the exact login page link.
   
   You are redirected to the Login Page Integration: <relying_party_application_name> page, where <relying_party_application_name> is the name of your relying party application.
   
   
4. Click Download Example Login Page under Option 2: Host the login page as part of your application.
   
   

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

This page calls the metadata feed using a script tag near the bottom of the HTML code and JavaScript functions for rendering the page are shown above that. Custom login pages can consume the metadata using pure client-side HTML and JavaScript (as shown in the example), however the feed can also be consumed by any language that supports JSON encoding to render a custom login control.

You can view the exact home realm discovery metadata feed URL for all of your relying party applications by completing the following steps:

1. Launch the ACS Management Portal. For more information, see ACS Management Portal.
   
   
2. Click Application integration in the tree on the left-hand side under the Development section, and then, on the Application Integration page, click the Login pages link.
   
   
3. Click the relying party application for which you want to view the exact login page link.
   
   You are redirected to the Login Page Integration: <relying_party_application_name> page, where <relying_party_application_name> is the name of your relying party application.
   
   

The URL is located under Option 2: Host the login page as part of your application.

The following is an example HRD 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 Windows 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 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.
  
  

Note
The JSON-encoded metadata feed may be subject to change therefore it is recommended that you do not cache it.

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 AD FS 2.0 and Windows Live ID 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 AD FS 2.0 identity providers via the ACS Management Portal. Returns an empty array if there are no suffixes configured.
  
  

The following example shows what the JSON feed would look like if two identity providers are configured—Windows Live ID and an AD FS 2.0. The user has set an image URL for Windows Live ID in the ACS Management Portal and associated an email domain suffix for the AD FS 2.0 identity provider.

Note
Line breaks have been added for readability and URLs have been simplified for brevity.

[ {
   "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”]
} ]