• Microsoft Exchange Server 2010 Administration Instant Reference
    Microsoft Exchange Server 2010 Administration Instant Reference
    by Ken St. Cyr
  • Mastering Microsoft Exchange Server 2010
    Mastering Microsoft Exchange Server 2010
    by Jim McBee, David Elfassy
  • Automating Active Directory Administration with Windows PowerShell 2.0 by St. Cyr, Ken, Hunter, Laura E. [Sybex,2011] (Paperback)
    Automating Active Directory Administration with Windows PowerShell 2.0 by St. Cyr, Ken, Hunter, Laura E. [Sybex,2011] (Paperback)

Handling Expired Passwords in AD FS 2012 R2

Since AD FS 2012 R2 came out, I’ve seen lots of folks complain about customization capabilities. Namely, that it’s less flexible than AD FS 2.x. This is true, since you can’t make server-side customizations like you could in the 2.x. However, I would argue that many of the things that need to be customized could be done via client-side customizations in JavaScript, which AD FS 2012 R2 does allow.

One such customization that I want to cover in this post is the ability to honor AD password expiration. If someone’s password is expired (or needs to be set on first login), the default behavior in AD FS is to give the user the following message:


What we’re going to do in this post is demonstrate how this default behavior can be changed, by redirecting the user to a custom “Change Password”. Keep in mind that while AD FS 2012 R2 does have a “Change Password” page built-in, it is only enabled for Workplace Joined devices. Because of this, we’re going to use a custom “Change Password” page in this example.

To achieve this, we’re going to use client-side JavaScript to detect when the password expiration message is given back to the user, change the message to tell the user that we’re redirecting them, and then do the redirect to the custom “Change Password” page.

Password Expiration Detection Script

The first thing we’re going to do is create the JavaScript code to detect whether AD FS gave the user a “password has expired” message instead of a successful sign-in. To do this, we need to examine the HTML element called “errorText”. This is the label that displays the “password has expired” message, as shown in the previous screen shot. We’re going to do a string comparison to determine if the “errorText” label starts with “Your password has expired.”, and wrap that in an “if” statement so we can do something as a result. (Note that I’m not doing a case-insensitive comparison in this example, so you have to make sure the casing is correct.)

Here’s the code that does this detection:

var custom_error = document.getElementById('errorText');
var custom_searchText = "Your password has expired.";
if (custom_error.innerText.substring(0, custom_searchText.length) == custom_searchText)
    // Do something here…

Inside the “if” statement is where we are going to change the text that the user sees and put the code to redirect the user to the “Change Password” page.

To change the text of the “errorText” label, we’ll use the following code:

custom_error.innerText = "Your password has expired. Redirecting...";

And this code does the redirect:

document.location.href = ‘https://www.contoso.com/ChangePassword’;

Ok, now let’s take all of that JavaScript and put it together. We’re going to save the following JavaScript code in a new file called custom.js. In this example, I’m going to save it in the folder “C:\CustomADFS” on the AD FS server:


var custom_error = document.getElementById(‘errorText’);
var custom_searchText = “Your password has expired.”;
if (custom_error.innerText.substring(0, custom_searchText.length) == custom_searchText)
    custom_error.innerText = “Your password has expired. Redirecting…”;
    document.location.href = ‘https://www.contoso.com/ChangePassword’;

Add the Custom Script to AD FS

Now that we have a JavaScript file with our custom code, we need to make that code available to AD FS so it can provide it to the client. To do this, we’re going to create a new Web Theme in AD FS. Web Themes are basically a collection of resources that are used to change the look and feel of the AD FS web pages. You can list the themes by running the following PowerShell command:


You’ll notice that there is a default theme called “Default”. You can’t modify this theme, so what we have to do is make a copy of it. Do that, we’re going to run the following PowerShell command, which will copy the Default theme into a new theme called “Custom”.

New-AdfsWebTheme -Name Custom -SourceName Default


You’ll notice that when the theme is created, it’s set with the same values as the default theme. Now, AD FS is still set to use the default theme, so we have to tell AD FS to use our new “Custom” theme instead. Do that, run the following PowerShell command.

Set-AdfsWebConfig –ActiveThemeName Custom


The next step is to add our custom.js file into the theme. Before we do that, let’s take a look at the resources that the theme currently has. You can do this by looking at the AdditionalFileResources parameter on the theme.

(Get-AdfsWebTheme -Name Custom).AdditionalFileResources


So here we have a couple of images and another JS file already there (onload.js), which AD FS uses by default. To add our custom.js file to the list, we run the following command:

Set-AdfsWebTheme -TargetName Custom –AdditionalFileResource @{Uri="/adfs/portal/script/custom.js"; Path="c:\CustomADFS\custom.js"}


I’ll point out here that typically, when you specify a collection in a PowerShell script, it overwrites the entire attribute. This particular cmdlet, however, appends the entry to the end of the existing collection. When adding the resource, we need to specify both the URL that the resource can be accessed under, in addition to the name of the file that we’ll populate that resource with. Now that the resource is added to AD FS, the contents of the custom.js file on disk are not automatically updated. Every time you make an update to custom.js, you will need to re-run the Set-AdfsWebTheme command to re-import the changes into AD FS.

Inject the Script into the Sign In Page

We’re almost there. The last step is to inject the script into the Sign-In page so that AD FS provides it to the client for execution. There are a couple of ways to do this, but in this example, we’re going to inject it straight into the Sign In page, specifically, via the customizable description text. The reason I chose this route is so that the custom script is only injected into the sign-in page. I could also have added it to the onload.js script that AD FS already has, but in doing so, it would be injected into every page that AD FS returns.

To inject our script, we’re going to run the following PowerShell command:

Set-AdfsGlobalWebContent –SignInPageDescriptionText "<script type=""text/javascript"" src=""/adfs/portal/script/custom.js""></script>"


And that’s it – now, when users attempt to log in with an expired password, they are redirected to our custom “Change Password” page.

Final Thing… Redirecting Back

One other thing I should mention is that I did not cover the process of redirecting the user back to their original URL after changing their password. This is something you’ll probably want to do, so that the user doesn’t have to browse back to their application and re-initiate the login process. To do this, you’ll want to base64 encode the sign-in page URL and pass it to your custom “Change Password” page – either through a query string parameter, a cookie, or maybe through a POST method instead of a redirect.

Once the “Change Password” page has the original URL, it can just do a redirect back to that URL after the password is changed, taking the user back to the AD FS sign in page. From there, the user can log in with their new password and get a token for that application.


Email <> Identity Service

A couple of months ago, Yahoo announced its intentions to recycle email addresses that have been dormant for the year. There’s been some discussion about this in the security communities because the implications of this could be bad.  This would allow the new owner of an email address to hijack identities at web sites that the previous owner used.

The core problem in all of this is that email is being used as an identity verification mechanism through “ownership-based” identity proofing. Many sites make the assumption that if the person can receive email at a particular email address, then they own that address.  Based on that assumption, many web sites are ok with allowing a user’s password to be reset over email. This is a faulty assumption for a couple of reasons:

  1. Some people share a single email address among many family members. I know a few families that have a single email address that each family member shares. The idea of this is noble – that there’s nothing to hide.  In practice, however, it does weaken the security of the family member’s identities on the Internet.
  2. There’s nothing to stop an email address from being transferred to a new owner.  I don’t think many us would even consider this scenario, because we just wouldn’t think that a large email provider would consider recycling email addresses. Since Yahoo is moving in this direction, this is going to be a real issue that we’re going to have to deal with. This becomes particularly problematic for my clients that are thinking of using identities asserted from social identity providers (such as Yahoo).
  3. You’re relying on the security of the email provider to prevent that email address from being stolen.  You’re only as secure as the weakest link in the identity chain. If a web site uses a strong password, but allows the password to be reset over email that is hosted by a provider that does not enforce a strong password, then that effectively reduces the security of web site for that user.

Email is great as a notification or message delivery mechanism, but it’s an awful identity service and shouldn’t be used that way.



A Look at Azure AD’s Web Sign-In Endpoints

If you’ve played with Azure AD at all, one thing you may have noticed is that there is this concept of “Azure AD Integrated Applications”.  You can create an “Integrated Application” in Azure AD and the application gets its own object representation in the directory. You can then manage the various settings related to how the application interacts with Azure AD, such as configuring federated authentication or directory access. In this post, I’m going to take a look at Azure AD endpoints that are related to Web Sign-In, with Azure AD acting as an IdentityProvider for an application.

One misconception that some folks may have is that Azure AD is a cloud identity service that can only be used for Azure applications.  This is far from the truth.  In fact, you can federate both custom and commercial on-premises applications with Azure AD, as well as applications from well-known Internet Service Providers.  In doing so, your Azure AD tenant acts as the Identity Provider STS for the application by providing a couple of different endpoints that the application can use (Note: The OAuth and Graph endpoints in Azure AD are not used for Web Sign-In, so I won’t be covering them in this post):


Your user principals could be synchronized from your on-premises directory to Azure AD via DirSync, or they could exist solely in Azure AD. Either way, when Azure AD is your identity provider, your application requests a token from one of the Azure AD Web Sign-In endpoints and your users authenticate with Azure AD directly. There are a number of endpoints available for your on-premises applications to use, including the WS-Federation and SAML-P endpoints to use for web sign in. Here is a screen shot of the endpoints available in one my current Azure AD tenants.


As I mentioned earlier, I’m going to ignore the Graph API and OAuth 2.0 endpoints for now and I’ll cover those in a later post.  The other 4 are the ones that are important for allowing your users to use Azure AD for web sign in to an application.

Federation Metadata

The Federation Metadata endpoint is your standard endpoint for auto-configuring the federation trust at the Relying Party. Similar to AD FS, Azure AD exposes the RoleDescriptor elements for WS-Federation and WS-Trust, in addition to the IDPSSODescriptor element for SAML-P 2.0.  One difference that you may notice from AD FS is that there’s no SPSSODescriptor element. This is because Azure AD is always acting as an Identity Provider STS, and not a Relying Party STS.

One thing to keep in mind is that when federating some non-Microsoft Relying Parties, you may have to save off a copy of the Federation Metadata file and edit it to remove the RoleDescriptor elements and the XML signature.  Some 3rd party applications (such as WebLogic) don’t properly ignore the RoleDescriptors and will therefore not import the metadata file when configuring the trust.  The reason you have to remove the XML signature also is because the signature is broken when you remove the RoleDescriptor elements.  If you leave the existing signature in place, the Relying Party won’t import it because of the signature mismatch. By removing the signature, you remove the signing check.  You are also removing a vital piece of security, by the way. Although, in this case we’re giving the RP a local copy of the file, so the lack of a signature is less of a concern since there’s no notion of a Man in the Middle attack.


The WS-Federation endpoint is the standard WS-Federation 1.2 protocol. When minting tokens from this endpoint, Azure AD uses the SAML 2.0 format:

This means that if you have an application that uses a SAML 1.1 security token handler, you cannot establish a direct trust with Azure AD.  If you need to have the STS for a SAML 1.1 over WS-Fed RP in the cloud, then you’re going to want to use an Access Control Service (ACS) instance to transition the SAML 2.0 token format to a SAML 1.1 token format.  One such example is in SharePoint 2010/2013 running in claims mode.  The screen shot below is from the web.config file on SharePoint 2013.  You’ll see where I’ve pointed out that SharePoint is using a SAML 1.1 token handler.  Because of this, if you federate SharePoint 2010/2013 with Azure AD directly, you get an error that says that it doesn’t know how to handle the SAML 2.0 assertion type.


So if your COTS applications use WIF and only support a SAML 1.1 token handler, then you’ll need the following architecture:



The SAML-P endpoints are for minting SAML 2.0 tokens over the SAML 2.0 protocol.  Here we have 2 endpoints – one for sign in and one for sign out.  When submitting an AuthnRequest to the SAML-P sign in endpoint, the request cannot be signed, as Azure AD does not support SAML authentication request signing. However, when submitting a LogoutRequest to the sign out endpoint, that request does need to be signed.  So in order for Azure AD to verify the signature, it has to have a copy of the public key that the Service Provider is using to sign the request with.  Now, you’ve probably noticed that there is no place in your published application in Azure AD to upload a certificate.  Instead, Azure AD only supports electronic transference of this certificate through a metadata endpoint on the Service Provider.  This is configured in the Single Sign On settings section of the published application configuration in Azure AD:


It’s not uncommon for SAML 2.0 Service Providers to have a metadata document at this endpoint that contains the signing key, but not all Service Providers have this. So if you don’t have a metadata endpoint with the public key included, and you want to use the sign-out endpoint, then you have to put in a support ticket so you can transfer that public key to us out of band.

Also, it’s important to note that your WIF-based applications will not be able to use these SAML-P endpoints. WIF does not natively support the SAML 2.0 protocol, only the WS-Federation protocol with SAML 1.1/2.0 assertions. However, a couple of years ago, we released a CTP for SAML 2.0 protocol support for WIF, though it was never released outside of CTP.  So more than likely you would be using these endpoints with your non-Microsoft applications, such as Java-based apps running on WebLogic or using something like the Oracle OpenSSO fedlet.

Location-Agnostic Applications

So because Azure AD uses the approach of publishing multiple endpoints that are available both in the Azure cloud and outside of the Azure cloud, Azure AD doesn’t really care where the application lives.  Applications that are on-premises, hosted in 3rd party Service Providers, or hosted in the Azure cloud can all take advantage of web sign in through Azure AD.  You just need to make sure that the application uses the appropriate endpoint, and also that it uses the endpoint properly.

I’ll be posting more in the future as I run through a few more scenarios that I’m working with, so keep an eye out for more coming down the pipe.



Identity-Based Decisions

I thought I'd follow-up on my post from this weekend and add some additional context around the need for strong proofing across the Internet as a precursor to an AzaaS model.   There is a very valid question that we all must ask - who do you think you are?  Without some form of strong identity proofing, your reputation is what defines you.  Unless there is a trusted 3rd party to vouch for you, then your identity is self-asserted.  Back in the day, the "my word is my bond" technique for trust was acceptable, but not so much today.

So what? For low value transactions, this is just fine.  At the end of the day, it doesn't matter if your Facebook profile is a real person. For higher value transactions, however, this is extremely important.  This is particularly true for the enterprise, where relationships with businesses, organizations, and consumers is the lifeblood of the organization. After all, the Service Providers need to make decisions based on the identities using the service. And if the identity is inaccurate, it's going to be a poor decision. When my supplier accesses my invoicing system, I really want to make sure that the person logging in is from the supplier.  If I'm buying a car and completing a title transfer online, I want to make certain that the person I'm giving my money to really owns the car.  This applies to virtually every area of online services - businesses, government, health care, etc...

Wouldn't it be interesting to imagine an online world where every identity is proofed to some level, and the level of that proofing follows the identity from place to place?  Would Service Providers make different decisions?  I think they would.  If you proved your digital identity in-person at, say, your local DMV and they gave you a strong credential to assert this proof, I'd be much more comfortable buying your car online. 

Authorization decisions are just another type of decision that a Service Provider must make about how someone uses their service. In order for us to starting thinking about a Trust Framework model to authorization across the Internet, the proofing problem needs to be solved. And there are, unfortunately, more questions than there are answers.  There are some consumer-based solutions out there now (the Symantec/Experian solution, for example), but we've got to break out of the bounds of the enterprise and make identity proofing available to the general public in wide-spread form.  NSTIC is laying these foundations, and I believe a hybrid public/private approach is the right approach - as long as the privacy-enhacing technology is in place as an identity mediator.


Authorization as a Service (AzaaS)

The other day, I stumbled upon a ZDNet blog post from 2006 - called "Identity Management as a Service".  Back then, and even now, we all had the "as a Service" bug - turning everything we can into a web service of some sort and tacking an "aaS" at the end.  The idea of IdMaaS is being thoughfully pursued, with folks such as our own Kim Cameron getting involved in the discussion.

The author of the aforementioned blog, Eric Norin, asserts that SalesForce.com may be a potential IdMaaS provider. Back in 2006, this would have made sense - identity was very much trust-driven model and organizations only wanted to deal with trusted entities.  While there is a great need for trusted identities, I think a lot of folks have realized that untrusted identities are still valuable, up to a certain extent. Rather than seeing SalesForce.com come to the table as a trusted identity provider, we've seen providers like Facebook and Twitter crop up and offer "less trusted" identities. "Social Identity Providers" have become the norm, and people just inherently understand and accept the fact that there's a chance the person sitting behind the keyboard is not who they claim to be.

To overcome this, the consumers of these identities (the Service Providers) have to put their own identity proofing mechanisms in place.  You can log into a web site with your Facebook account and the Service Provider doesn't really care if your identity has been proofed. However, when it comes time to pay for something, then the SP cares a lot because their business model is dependent on valid, legal transactions. The higher value the transaction, the more important the proofing. With initiatives like NSTIC calling for safe and private identity usage online, it's vitally important that we solve this high assurance identity problem. By the way, did you notice that Microsoft is involved in one of the NSTIC pilots? :)

So while social identity providers are great for providing identities with a low level of assurance, I don't think we'll see truly effective IdMaaS until providers adopt strong proofing mechanisms and we have a well-adopted, trusted exchange for "high assurance" identities.

However, hidden among all of this is an even greater need.  I've felt for quite some time that we all spend too much time talking about "Identity" Management and not enough time talking about "Access" Management.  After all, identity is a 4-legged stool (Administration, Authentication, Authorization, and Auditing), and we focus a lot on the first two legs (Administration and Authentication). We can have the most thoughtful and well-adopted IdMaaS service in place, but unless we get to a universally accepted authorization model, we're missing a large part of the identity puzzle. So I'm going to join in on the "aaS" fad and suggest that we start thinking about "Authorization as a Service" now before we get to the point where we wish we had thought about it sooner.