stevenha

Updated Snapshot report of Public Folder Usage Script

Steve Halligan — Thu, 21 Feb 2013 19:13:24 GMT

Updated my Snapshot report of Public Folder Usage Script:

Fixed Last Modified Time so it actually works (dang typo)
Added "Email Enabled" to report
Added "Primary SMTP Address" to report if folder is email enabled
Added Progress bar so you can tell it is actually still running

You can download it here:

http://gallery.technet.microsoft.com/office/Snapshot-report-of-Public-21235573

Offline Address Book Full Download Fails if Hardware Load Balancer in use

Steve Halligan — Wed, 09 Jan 2013 19:26:00 GMT

I came across an interesting scenario relating to the use of a Hardware Load Balancer publishing Exchange Client Access Servers. This relates specifically to how CAS distributes OAB and how Outlook decides which files it needs to perform an OAB update.

First, let's walk through how it is supposed to work starting from a new Outlook Profile (if you already know the OAB download/update process, feel free to skip to the next section):

Outlook finds (via AutoDiscover) the url to use to connect to the OAB distribution server. It will look something like https://mail.contoso.com/OAB/<guid of OAB>/
Outlook attempts to download the OAB.XML file at that URL. This is the "manifest" file that lists out the other files that Outlook will need to download.
Outlook attempts to download the "template" file for whatever language Outlook is running. For English, it finds the entry in the oab.xml that specifies langid 0409. The line in the OAB.xml looks something like this:
<Template seq='7' ver='7' size='6028' uncompressedsize='26470' SHA='df80ec818f23bb6b23aa55cbc49d45986604af34' langid='0409' type='windows'>
1efdeb0a-56fe-488d-aed7-b3d9179193a2-lng0409-7.lzx
Outlook attempts to download the template file 1efdeb0a-56fe-488d-aed7-b3d9179193a2-lng0409-7.lzx
Outlook finds the file name for the full OAB download in the manifest
<Full seq='7' ver='32' size='2408' uncompressedsize='11481' SHA='c3874445e4942eac788523db974e60a37463cabb'> 1efdeb0a-56fe-488d-aed7-b3d9179193a2-data-7.lzx </Full>
Outlook attempts to download the full OAB file 1efdeb0a-56fe-488d-aed7-b3d9179193a2-data-7.lzx

Now Outlook has an up-to-date OAB. Outlook and the Server track OAB status using a sequence number. In the above manifest, you can see the current sequence number of the OAB is 7.

Next time (say 24 hours later) Outlook goes to update OAB it goes through the following process.

Outlook finds (via AutoDiscover) the url to use to connect to the OAB distribution server. It will look something like https://mail.contoso.com/OAB/<guid of OAB>/
Outlook attempts to download the OAB.XML file at that URL. This is the "manifest" file that lists out the other files that Outlook will need to download.
Outlook compares its own sequence number to that in the manifest. In our example, Outlook downloaded sequence 7. When looking at the manifest we can see that the server is up to sequence 9
<OAL id='1efdeb0a-56fe-488d-aed7-b3d9179193a2' dn='/' name='\Global Address List'>
        <Full seq='9' ver='32' size='2422' uncompressedsize='11496' SHA='6852ea7fc58cfe2788766efbec61bc27cf62a96e'>
            1efdeb0a-56fe-488d-aed7-b3d9179193a2-data-9.lzx
        </Full>
Outlook looks in the manifest to see if there are differential files available to get from sequence 7 to sequence 9
<Diff seq='9' ver='32' size='122' uncompressedsize='11496' SHA='05eed595e0fdf88245a48d42d80431337dff36cc'>
            1efdeb0a-56fe-488d-aed7-b3d9179193a2-binpatch-9.lzx
        </Diff>
        <Diff seq='8' ver='32' size='132' uncompressedsize='11494' SHA='4e0e62a0c3af3786310f9bd6a9b802879bcde07f'>
            1efdeb0a-56fe-488d-aed7-b3d9179193a2-binpatch-8.lzx
        </Diff>
They are there! Outlook grabs those 2 files and applies them in order. Outlook is now up-to-date at sequence 9.

However, if either of these items are true:

The diff files that Outlook needed to get current aren't available (they are kept for 30 days by default)
New profile

Outlook will fall back to a full download and follow the first procedure.

When good manifests go bad…

Now…on to the meat of the matter.

Consider this scenario:

Client Access web based services live behind a hardware load balancer.
Outlook decides it needs to do a full OAB download.

Outlook goes to the OAB URL and grabs the OAB.XML file. As laid out in the Full download procedure above, the first thing Outlook is going to look for is the template file.

And then…failure. If you initiated the download manually, you may see an 0x80200011 error code. You will also see an Event ID 27:

Log Name: Application

Source: Outlook

Date: 12/20/2012 1:20:01 PM

Event ID: 27

Task Category: None

Level: Warning

Keywords: Classic

User: N/A

Computer: workstation1.corp.contoso.com

Description:

OAB Download Failed. (Result code in event data).

Event Xml:

<Channel>Application</Channel>

<Computer>cas.corp.contoso.com</Computer>

</System>

<Data>OAB Download Failed. (Result code in event data).</Data>

</EventData>

</Event>

If you review Dave Goldman's excellent blog post on this subject (http://blogs.msdn.com/b/dgoldman/archive/2006/06/19/troubleshooting-offline-address-book-downloads-with-outlook-diagnostic-logging-_2800_event-id-27_2900_.aspx ) you will see that the binary data starts with 0C which indicates that Outlooks is doing a full download. You can also see Outlook's current OAB sequence number 0817 and the Server's current sequence number 0C17. To translate these hex sequence numbers into decimal, flip the bytes. The client translates to 5896 and the server to 5900 in this example.

Having said all of that, there is little indication as to why the download failed. To attempt to see what is really going on, we can use the bitsadmin tool. The Binary Intelligent Transfer agent is the code that performs the OAB download for Outlook and it is a built-in part of Windows.

C:\>bitsadmin /list /verbose

BITSADMIN version 2.0 [ 6.6.2600.2180 ]

BITS administration utility.

Listed 0 job(s).

Well, that is not very helpful…we need to run this tool at the moment of the failure.

Let's try this batch file:

@echo off

:work

bitsadmin /list /verbose >> c:\bitsoutput.txt

goto work

Looking over the output file that was created, we see Outlook grabbing the OAB.xml file successfully and then it moves on to download the template file:

BITSADMIN version 2.0 [ 6.6.2600.2180 ]

BITS administration utility.

GUID: {D5820AE4-24C8-4C43-8B1D-728E3C16CB4E} DISPLAY: Microsoft Outlook Offline Address Book

TYPE: DOWNLOAD STATE: CONNECTING OWNER: CORP\owells

PRIORITY: NORMAL FILES: 0 / 1 BYTES: 0 / UNKNOWN

CREATION TIME: 1/8/2013 11:23:46 AM MODIFICATION TIME: 1/8/2013 11:23:47 AM

COMPLETION TIME: UNKNOWN ACL FLAGS:

NOTIFY INTERFACE: UNREGISTERED NOTIFICATION FLAGS: 3

RETRY DELAY: 600 NO PROGRESS TIMEOUT: 1209600 ERROR COUNT: 0

PROXY USAGE: PRECONFIG PROXY LIST: NULL PROXY BYPASS LIST: NULL

DESCRIPTION: Microsoft Outlook Offline Address Book Template

JOB FILES:

0 / UNKNOWN WORKING https://mail.contoso.com/OAB/9165d096-ff22-4a79-ba2d-b47d8645e220/418771d0-6766-4c27-ab27-b6068ffb56a8-lng0409-5958.lzx -> C:\Documents and Settings\owells\Local Settings\Application Data\Microsoft\Outlook\tmplts.tm_

NOTIFICATION COMMAND LINE: none

Listed 1 job(s).

Great. You can see it connecting to grab the template file for English with the sequence number 5958.

Uh oh!

BITSADMIN version 2.0 [ 6.6.2600.2180 ]

BITS administration utility.

GUID: {D5820AE4-24C8-4C43-8B1D-728E3C16CB4E} DISPLAY: Microsoft Outlook Offline Address Book

TYPE: DOWNLOAD STATE: ERROR OWNER: CORP\owells

PRIORITY: NORMAL FILES: 0 / 1 BYTES: 0 / UNKNOWN

CREATION TIME: 1/8/2013 11:23:46 AM MODIFICATION TIME: 1/8/2013 11:23:50 AM

COMPLETION TIME: UNKNOWN ACL FLAGS:

NOTIFY INTERFACE: UNREGISTERED NOTIFICATION FLAGS: 3

RETRY DELAY: 600 NO PROGRESS TIMEOUT: 1209600 ERROR COUNT: 1

PROXY USAGE: PRECONFIG PROXY LIST: NULL PROXY BYPASS LIST: NULL

ERROR FILE: https://mail.contoso.com/OAB/9165d096-ff22-4a79-ba2d-b47d8645e220/418771d0-6766-4c27-ab27-b6068ffb56a8-lng0409-5958.lzx -> C:\Documents and Settings\owells\Local Settings\Application Data\Microsoft\Outlook\tmplts.tm_

ERROR CODE: 0x80190191 - The requested resource requires user authentication.

ERROR CONTEXT: 0x00000005 - The error occurred while the remote file was being processed.

DESCRIPTION: Microsoft Outlook Offline Address Book Template

JOB FILES:

NOTIFICATION COMMAND LINE: none

Listed 1 job(s).

Requires authentication??? I bet that is a bit of a misinterpretation of what happened. How about we go see what files are on the server? When we looked at the OAB directory (c:\program files\microsoft\exchange\v14\client access\oab) we see that there is a template file there…but it has a sequence number of 5961! Unlike the binpatch diff files, Exchange only keeps the latest template file. If we go looking for 5958 and the server has 5961, we will not find it. The above error really means "file not found".

Why the heck did we go looking for an old template file? Looking at the OAB.xml file on the server, it has the proper sequence number and filename for the template file.

Were we not looking at the current OAB.xml?

We tried opening OAB.xml in IE on the client machine. What the…why does this OAB.xml seem to indicate the 5958 is the current sequence number?

So, we now know what is not working…we can't go looking for old sequences…that won't work.

But, how did this happen?

The Answer (at long last):

The default configuration on many hardware load balancers is to cache some http content. We were looking at a cached copy of the oab.xml! Thanks for the help, Mr. Load Balancer!

The Solution:

Turn off http caching on the load balancer. You can either disable it for all Exchange Web services, the OAB vdir only, or just the OAB.xml file depending on your preference and your load balancers capabilities.

Snapshot report of Public Folder Usage (name, last access, items, etc)

Steve Halligan — Fri, 04 Jan 2013 19:45:00 GMT

This is a simple script that will dump info about your public folders to a csv file. The tricky bit here is that it combines data values from get-publicfolder, get-publicfolderstatistics and get-publicfolderclientpermissions into one CSV report.

Find it at http://gallery.technet.microsoft.com/office/Snapshot-report-of-Public-21235573

“The Public Group Cannot Be Displayed” error attempting to modify members of a large DL in Outlook with Exchange 2010

Steve Halligan — Thu, 29 Nov 2012 17:42:00 GMT

Ever see this error when you try to modify members of a large (1000+) member DL using Outlook when your mailbox is on Exchange 2010?

"The public Group cannot be displayed. The operation failed"

"The public group cannot be displayed. Too many names have been found in the directory service or the server has exceeded its time limit for searching. Type more letters of the name and try again"

If you clear this error, you may see a partial list of the DL members displayed. You will be able to successfully add members to the DL. You will also be able to remove members, if they managed to make it in the partial list.

Poking around in the application log of the Client Access Server you are connected to shows nothing out of the ordinary…even if you ramp up diagnostic logging.

The reason this error pops up, and the reason why nothing is logged, is because the CAS is doing exactly what you told it to do. Well…to be fair…it is doing exactly what its default settings told it to do. It is throttling your connection.

The specific throttling policy parameter that relates to this is RCAPercentTimeInAB. By default, this parameter is blank in the Default Throttling Policy that ships with Exchange 2010. If I am reading TechNet right, blank mean default and default maps to a setting of '5'. For all of these *PercentTimeIn* parameters, the number indicates what percentage of a minute you can use in that minute. '5' would therefore equate to 3 seconds (5% of 60 seconds). If you use your budget of 3 seconds, you need to wait for the minute to roll over to get a new 3 second allocation. Outlook is not that patient (nor are most end-users) and blows the error above.

I have found that a setting of 20 (which would equate to 12 seconds) is adequate for most deployments, but your needs could differ. I highly recommend experimenting with this setting on a "test" throttling policy that you apply to a few test users before you roll anything into the default policy.

For more details on creating and setting Client Throttling Policies, see Understanding Client Throttling -- TechNet

Bonus Track

If you are using Outlook 2010 and the DL in question is 5000+ users, you may also see this error when you try to look at the properties of the DL:

"Unable to connect to retrieve additional data"

To fix this one, you need an update to Outlook to get rid of a hard coded limit of 500 DL members.

Member names are not displayed in a distribution list in Outlook 2010 KB2598291

This fix was delivered in the April 24, 2010 Outlook 2010 hotfix package

Output Exchange 2010 RBAC Role Entries in HTML Report

Steve Halligan — Thu, 15 Nov 2012 21:08:28 GMT

***THIS ONLY WILL WORK IN POWERSHELL V3 (Win8 and Server 2012)***

The script will run in Powershell V2, but the data in the output tables will contain only the type information and not the actual data.

To use this script, you must be connected to Exchange remote powershell. Replace the URI below with the URI for your CAS. Replace "basic" with whatever authentication means you allow on the "powershell" IIS vdir on CAS. This may be "kerberos" if you are on a domain joined machine.

Copy Code

PowerShell

Edit|Remove

$cred = get-credentials

$session = new-pssession -configurationname Microsoft.Exchange -connectionuri "https://mail.contoso.com/powershell" -authentication basic -credentials $cred

import-pssession $session

This script with iterate through all roles defined and then through each entry.

It will output all of the allowed Commandlets for each role and what parameters are available.

Example Output:

Role:Recipient Policies

Name	Parameters
Write-AdminAuditLog	Comment Confirm Debug DomainController ErrorAction ErrorVariable OutBuffer OutVariable Verbose WarningAction WarningVariable WhatIf
Set-ThrottlingPolicyAssociation	Confirm Debug DomainController ErrorAction ErrorVariable Identity OutBuffer OutVariable ThrottlingPolicy Verbose WarningAction WarningVariable WhatIf

You can download it here

Script to convert an MS Online Directory Immutable ID to an AD GUID (and Vice Versa)

Steve Halligan — Tue, 13 Nov 2012 18:25:13 GMT

This script can take an ImmutableID found in the DirSync Metaverse or via get-msoluser and output the GUID of the corresponding object from the SOURCE AD.

It can also take the Source AD GUID and tell you what the ImmutableID should be.

Useful in troubleshooting DirSync issues and determining which AD Object maps to which MSOD object.

Examples:
To convert a GUID to an Immutable ID: GUID2ImmutableID.ps1 '748b2d72-706b-42f8-8b25-82fd8733860f'
To convert an ImmutableID to a GUID: GUID2ImmutableID.ps1 'ci2LdGtw+EKLJYL9hzOGDw=='

It can be found at: http://gallery.technet.microsoft.com/office/Covert-DirSyncMS-Online-5f3563b1

Customizing the ADFS forms based login page

Steve Halligan — Mon, 12 Nov 2012 21:20:00 GMT

By default, the ADFS forms based login page supplied by an ADFSProxy server is a best pretty boring and at worst inaccurate.

Out of the box, it looks like this:

Wouldn't it be nice to:

Add some pretty logos?
Correct that Domain\username example so it show UPN format?
Change the instruction text?
Give the page a better title than "Sign In"?
Remove or change that hostname header above the login box?
Add an "Authorized Use" text block at the bottom to keep the lawyers from bugging you?

Well, if you agree, today is your lucky day!

Please, keep in mind that it is quite possible (likely even) that some of the changes I describe below will be overwritten when you apply any update to ADFS. Make sure you:

Back up your original files, in case you need to revert to the stock config
Have backup copies of your changes, in case they get stomped on by an update.
Understand that you may have to re-do your changes after an update as the underlying files may change.

These instructions are applicable to ADFS 2.0 with update rollup 2. I have not tested this with any other past or future version.

Having covered all necessary behinds…on with the show

Adding a Logo

Logo image file should be 600x100
Save image file to c:\inetpub\adfs\ls\logo.jpg (or logo.png)
Open c:\inetpub\adfs\ls\web.config in notepad
Locate text
Remove the "" to uncomment the section. Change filename to match the logo you saved.
Save file and close

Change the "Example" Instructions

Go to C:\inetpub\adfs\ls\App_GlobalResources
Edit file CommonResources.en.resx in Notepad (replace the "en" with your localization code if not English)
Locate text:
<data name="UsernameExample" xml:space="preserve">
<value>Example: Domain\Username</value>
</data>
Edit this text to be what you want
Save File and close

Change the Instruction Text

Edit CommonResources.en.resx in Notepad as per item above
Locate text:

<data name="FormsSignInHeader" xml:space="preserve">

<value>Type your user name and password.</value>

</data>
Edit this text to be what you want
Save file and close

Change the Page Title

Go to C:\inetpub\adfs\ls\App_GlobalResources
Edit file CommonResources.en.resx in Notepad
Locate text:
<data name="FormsSignInPageTitle" xml:space="preserve">
<value>Sign In</value>
</data>
Edit this text to be what you want
Save File and close

Remove or Change the Hostname Header Above the Login Box

Go to C:\inetpub\adfs\ls\MasterPages
Edit MasterPage.master.cs in Notepad
Locate text:
{
PageTitleLabel.Text = Page.Title;
STSLabel.Text = FriendlyName;
}
Change this text to what you want. Your text MUST BE IN QUOTES. Like this
STSLabel.Text = "Contoso Limited Single Sign On";
Save File and close

Add an "Authorized Use" disclaimer or other text at bottom of page

Go to C:\inetpub\adfs\ls\MasterPages
Open MasterPage.Master in Notepad (not MasterPage.Master.cs)
Locate text at the end of the file:
<div class="MainActionContainer">
<asp:ContentPlaceHolder ID="ContentPlaceHolder1" runat="server">
</asp:ContentPlaceHolder>
</div>
</div>
</form>
</body>
</html>
Add a section here (added text hightlighted):
<div class="MainActionContainer">
<asp:ContentPlaceHolder ID="ContentPlaceHolder1" runat="server">
</asp:ContentPlaceHolder>
</div>
<div class="GroupLargeMargin">
<div class="TextSizeLarge">
<asp:Label ID="STSFooter" runat="server"></asp:Label>
</div>
</div>
</div>
</form>
</body>
</html>
Save file and close
Edit file MasterPage.Master.cs in Notepad
Locate text:
protected void Page_Load( object sender, EventArgs e )
{
PageTitleLabel.Text = Page.Title;
STSLabel.Text = FriendlyName;
}
Add a line (added text highlighted)
protected void Page_Load( object sender, EventArgs e )
{
PageTitleLabel.Text = Page.Title;
STSLabel.Text = FriendlyName;
STSFooter.Text = "This is a secured, private computer system owned by Contoso. All Information contained on this system is deemed to be PRIVATE, PROPRIETARY, CONFIDENTIAL and the property of Contoso, Inc., its affiliates, divisions or subsidiaries. Unauthorized access or use is strictly prohibited. Any use of Contoso resources must be in compliance with Contoso policies including Electronic Mail/Communication; Information System Usage; Corporate Disclosure; Unauthorized Use of Software and the Code of Business Ethics. By using Contoso resources, you agree to comply with Contoso policies. Any unauthorized access to or use of Contoso Resources may be punishable in a court of law and may include termination of employment or contract with Contoso.<br>To protect your account from unauthorized access, Outlook Web Access automatically closes its connection to your mailbox after a period of inactivity. If your session ends, refresh your browser, and then log on again.";
}
This text is all on one line. If you need or want a linefeed in the text use <br>, like here.
Save file and close

These are just a few of the theme elements you can fiddle with on the ADFS Proxy form. As you play with these, you will see other text tidbits you may want to adjust. Just be certain to follow my warnings and back everything up before and after your fiddling.

Steve

An ADFS Claims Rules Adventure

Steve Halligan — Mon, 08 Oct 2012 16:58:00 GMT

UPDATE: A powershell based GUI script has been released to make some of this easier (http://gallery.technet.microsoft.com/office/Client-Access-Policy-30be8ae2 ) The story below can still serve as a useful tool to understanding what is going on behind the scenes and can help if the GUI doesn't meet your needs

Notes from the field

Customers can come up with some fairly complex requirements for access control. It can be a challenge to accommodate these requirements in an Office 365 world. The ADFS claims rule system in ADFS 2.0 UR1 provides some powerful options to implement these controls—and some limitations.

The requirements:

No one shall access email via Outlook when off the corporate network
Members of a specific security group may not use ActiveSync
Members of a specific security group may not access OWA off the corporate network
All OWA users must log in via a forms based login

It is important to note that the rule processing system always processes all rules. It is NOT a first match system. Because of this, the first rule is most always an "allow everything" rule followed by additional rules that block some access. Schematically, it could look like this:

Allow everyone
Block members of the group "Bigwigs" from access to OWA
Allow the CEO access to OWA

When the CEO attempts to log in to OWA: Rule #1 allows him, Rule #2 blocks him, and then Rule #3 allows him. It is the state of the last matching rule that determine his final outcome. If the CIO were to attempt to log in, he would only match rules 1 and 2 and therefore would be blocked.

Requirement #1: No one shall access email via Outlook when off the corporate network

This is a fairly common requirement in a lot of enterprise Exchange environments. Security folks get a bit freaked out by the thought that a user could set up Outlook on a home machine. Meeting this challenge is pretty straightforward with ADFS 2.0 claims rules.

First, let's review a bit how ADFS claims work in an Office 365 deployment. There are two flavors of ADFS claims requests: Active and Passive. When a claims request is created and submitted by the service (O365) it is an "active" request. This seems kind of counter-intuitive since you (the client) don't have to do anything for these requests. The active/passive nature of the request refers to the participation of the _service_, not the client. Examples of O365 services that use active claims requests are Outlook 2007/2010 (RPC + HTTPS, EWS), Outlook 2011 for Mac (EWS), ActiveSync, Autodiscover and Lync Online.

A passive claims request is when the service sends you off to get the claim yourself. The main examples of this in O365 are OWA and Sharepoint Online. When you try to log in to OWA in O365 (and you are using federated identity) your browser is redirected to your ADFS endpoint. There you provide your credentials (either via a web form, basic authentication pop-up or integrated auth.), get your token and then return to OWA with your token in hand.

Back to the issue at hand: Blocking Outlook when client is not connected to the corporate network. To translate that into ADFS speak—We need to block active ADFS claims for the RPC+HTTPS and EWS services if the IP address doesn't match a known set of corporate addresses.

Logically, the rule will look like this:

If {

{ClientApplication is RPC

ClientApplication is EWS}

AND

ClaimType is Active

AND

ClientIPAddress is not in <corporate ip address list>}

THEN DENY THE CLAIM

Now let's translate that to ADFS Claim Rule language:

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy"]) &&

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path", Value == "/adfs/services/trust/2005/usernamemixed"]) &&

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application", Value == "Microsoft.Exchange.RPC|Microsoft.Exchange.WebServices"]) &&

NOT exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip", Value =~ "<public NAT addresses>"])

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/deny", Value = "true");

Makes perfect sense, right? Oh…it doesn't? Allow me to break it down:

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy"])

The 'Type' x-ms-proxy exists. This simply means that the claim came through an ADFS Proxy server (or other compatible proxy). Note: we are not checking the 'value' for this type, just that the type exists.

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path", Value == "/adfs/services/trust/2005/usernamemixed"])

The type x-ms-endpoint-absolute-path exists and has a value of usernamemixed. This is the name of the endpoint for _Active_ ADFS Claims. Summary: This is an active ADFS claim.

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application", Value == ""Microsoft.Exchange.RPC|Microsoft.Exchange.WebServices"])

ClientApplication is RPC or WebServices. We can use this 'or' (using the '|' character) syntax to check the value field.

NOT exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip", Value =~ "\b192\.168\.4\.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-5][0-9])\b|\b10\.3\.4\.5\b"])

The value for the type x-ms-forwarded-client-ip has a value that DOES NOT MATCH the regular expression "<public NAT addresses>". That brings up two important questions:

Where does that "x-ms-forwarded-client-ip" come from and what values should I expect to see there?
What does the format of the regular expression look like?

According to TechNet:

"This AD FS claim represents a "best attempt" at ascertaining the IP address of the user (for example, the Outlook client) making the request. This claim can contain multiple IP addresses, including the address of every proxy that forwarded the request. This claim is populated from an HTTP header that is currently only set by Exchange Online, which populates the header when passing the authentication request to AD FS."

(http://technet.microsoft.com/en-us/library/hh526961(v=ws.10).aspx)

So, the value is going to be the border IP address that Exchange Online (EXO) sees for the client. That would be either the border firewall doing NAT/PAT or the border Proxy server. Exchange Online add this IP to the ADFS claim request. Perfect for our Outlook scenario here: Outlook attempt to connect to EXO, EXO builds up a claims request that includes the client IP and heads out to the ADFS endpoint to submit the request.

The second question is a bit easier (or perhaps a bit harder—regular expressions can get complicated) due to the fact that the regular expression format follows the general rules for regular expressions. The Internet is full of regular expression examples to filter IP addresses. For example, let's say that your network has one block of addresses in use in a NAT pool: 192.168.4.0-192.168.4.255. You also have one satellite office with a single public IP address: 10.3.4.5. An expression you may use could be:

"\b192\.168\.4\.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-5][0-9])\b|\b10\.3\.4\.5\b"

To break that down:

\b192\.168\.4\.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-5][0-9])\b applies to the 192.168.4.0-255 network.

\b192\.168\.4\. matches 192.168.4.

[1-9] matches address ending in 1-9

[1-9][0-9] matches 10-99

1[0-9][0-9] matches 100-199

2[0-5][0-9] matches 200-259 (yeah…I know a few more than needed)

The '|' represent "or"

\b10\.3\.4\.5\b applies to the 10.3.4.5 address.

These can get tricky. I recommend you use a regular expression verification tool and test.

Finally, if ALL of these conditions are true:

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/deny", Value = "true");

We deny the claim.

If any one of the elements of the rule evaluate to false, the entire rule is skipped. So, if the client IS coming from one of the addresses that match the regular expression, they do not match this rule.

Requirement #2: Members of a specific security group may not use ActiveSync

The previous example illustrated how to allow or block users based upon where they are. This is a simple example of how to block users based upon who they are.

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy"]) &&

exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value =~ "Group SID value of allowed AD group"]) &&

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application, Value == "Microsoft.Exchange.ActiveSync"])

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/deny", Value = "true");

The new element here from the previous example is the "groupsid" type. Yeah, you need to dive into AD and hunt down the SID of the group in question. As is hinted by the "=~" operator, you could create a regular expression that would match more than one group. You could also use the "==" operator and the "|" to do a multiple "or" match.

That one was easy—sets us up well for the next. Which gets a bit…complicated.

Requirement #3: Members of a specific group may only use OWA on the corporate network

We built a rule above that did something very similar for Outlook, couldn't we just add on or slightly alter that rule? Nope, we can't. OWA login uses a passive ADFS claim, so the behavior is different. With Outlook, or other active claims, all requests come from O365 and land on the external ADFS proxy. To determine if a user is internal or external, we have to examine the "x-ms-forwarded-client-ip" value. With a passive claim request, like OWA, the client's browser will be connecting directly to the ADFS endpoint (sts.contoso.com for example). So, we can control who gets in based upon where they are asking. If they ask the external proxies (and they are in the specified group) we say "no". If they ask the internal ADFS servers we say "yes".

The rule to accomplish this would look something like this:

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy"])

&& exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value =~ "S-1-5-21-299502267-1364589140-1177238915-114465"])

&& exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path", Value == "/adfs/ls/"])

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/deny", Value = "true");

Line 1: Request went through a proxy

Line 2: User is a member of the specified group

Line 3: This is a passive claim to the /adfs/ls/ endpoint

Line 4: Deny

If they hit the internal ADFS servers directly, line 1 would be false and they would be allowed in.

Requirement #4: Oh…your solution to #3 doesn't work because we want everyone to use forms-based authentication

Well…shoot. Easy enough to fix, right? Send everyone to the ADFS proxy and add in a line to the above rule that specifies which client IP addresses are allowed. Something like:

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy"])

&& exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value =~ "S-1-5-21-299502267-1364589140-1177238915-114465"])

&& exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path", Value == "/adfs/ls/"])

&& NOT exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip", Value =~ "\b192\.168\.4\.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-5][0-9])\b|\b10\.3\.4\.5\b"])

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/deny", Value = "true");

I hope the blaring red background illustrates the point that this will not work. Why not? Scroll up a bit to the section on blocking Outlook based on IP address. Notice what fills in that x-ms-forwarded-client-ip? EXO. In this example we are dealing with _passive_ ADFS claims. EXO is not creating this claim—the user is hitting the ADFS login page directly. If you turn on this rule, everyone in the specified group will be blocked no matter where they are coming from. The x-ms-forwarded-client-ip type does not exist at all, so that line will evaluate to true. In order to make it false (and thereby stopping the deny rule from firing on someone) the element would need to exist AND the value need to match the regular expression.

If we can't use the client's source IP as a filter, how can we solve this problem?

The answer lies in an ADFS claim element that we have been checking all along, but not checking it fully. Let's look at the debug log (for more on turning on debugging for ADFS see: http://technet.microsoft.com/en-us/library/adfs2-troubleshooting-configuring-computers(v=WS.10).aspx ).

Event ID 151 AD FS 2.0 Tracing:

ClaimType http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname Value CONTOSO\USER1 ValueType http://www.w3.org/2001/XMLSchema#string Issuer AD AUTHORITY OriginalIssuer AD AUTHORITY

ClaimType http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name Value CONTOSO\USER1 ValueType http://www.w3.org/2001/XMLSchema#string Issuer AD AUTHORITY OriginalIssuer AD AUTHORITY

ClaimType http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid Value S-1-5-21-3640651473-4051545122-2937135913-1136 ValueType http://www.w3.org/2001/XMLSchema#string Issuer AD AUTHORITY OriginalIssuer AD AUTHORITY

ClaimType http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid Value S-1-5-15 ValueType http://www.w3.org/2001/XMLSchema#string Issuer AD AUTHORITY OriginalIssuer AD AUTHORITY Value S-1-5-11 Value S-1-5-2 Value S-1-5-32-545 Value S-1-1-0 Value S-1-5-21-3640651473-4051545122-2937135913-513

ClaimType http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid Value S-1-5-21-3640651473-4051545122-2937135913-513 ValueType http://www.w3.org/2001/XMLSchema#string Issuer AD AUTHORITY OriginalIssuer AD AUTHORITY

ClaimType http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod Value http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password ValueType http://www.w3.org/2001/XMLSchema#string Issuer LOCAL AUTHORITY OriginalIssuer LOCAL AUTHORITY

ClaimType http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant Value 2012-04-19T17:32:41.459Z ValueType http://www.w3.org/2001/XMLSchema#dateTime Issuer AD AUTHORITY OriginalIssuer AD AUTHORITY

ClaimType http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy Value adfs01p ValueType http://www.w3.org/2001/XMLSchema#string Issuer CLIENT CONTEXT OriginalIssuer CLIENT CONTEXT

</Claims>

We have been checking for the existence of the x-ms-proxy element, but we haven't looked into its value. The value identifies the name of the proxy server that the request passed through. What if we could tell if a user was internal or external based upon which proxy server they came through?

With this change, internal OWA users will land on internal ADFS Proxy servers and external OWA users will land on external ADFS Proxy servers. That will allow us to add a rule like this:

exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy", Value =~ "\badfsp[0-9][0-9]\b"])

&& exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value =~ "S-1-5-21-299502267-1364589140-1177238915-114465"])

&& exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path", Value == "/adfs/ls/"])

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/deny", Value = "true");

Line 1: User is coming through an ADFS Proxy and that proxy has a name that matches ADFSP##

Line 2: User is in the specified group

Line 3: User is hitting the passive endpoint

Line 4: Deny the claim

If a user in the specified group presents a claim to ADFS from outside the network, all elements of this rule will be true and the claim will be denied. If the same user is inside the network and is using one of the internal proxies, line 1 will be false (the proxy name will not match ADFSP##) and the claim will be allowed.

For illustration purposes, we can express the same thing in a slightly different way:

NOT exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy", Value =~ "\badfspi[0-9][0-9]\b"])

&& exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value =~ "S-1-5-21-299502267-1364589140-1177238915-114465"])

&& exists([Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path", Value == "/adfs/ls/"])

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/deny", Value = "true");

Line 1: The user is NOT coming through an ADFS Proxy that matches ADFSPI##

…

While you may not need to meet access control requirements this complex, I hope that these notes provide some enlightenment into the ADFS claim rule language.