SharePoint MetaData and Classification

Securing Mobile Access to SharePoint 2010

Microsoft SharePoint 2010 has some great capabilities built in for accessing SharePoint from a mobile device. Some mobile browsers are fully supported out of the box, and others are partially supported today, with more support to come in the future. Lately I’ve been researching how we secure access to SharePoint from a mobile device or tablet for a particular customer, and there are several useful blog posts already out there that have been an enormous help. Securing access from a mobile device is becoming a critical part of security planning for SharePoint, as the phenomenon of Bring Your Own Device to work just continues to grow. In this short post, I’d like to highlight those articles and point readers to them as an important resource as they think about how to allow secure access to SharePoint from a mobile device.

With the phenomenon of Bring Your Own Device to work, IT departments no longer have complete control of which devices are being used to access corporate resources. People want to use their own mobile device or tablet in order to get their work done. And, enterprises want to allow this because of the cost savings involved, despite the risks.

In fact, a recent Forrester survey found that 81% of enterprises will support or are interested in supporting the iPad this year. This means that mobile access must be considered when determining how to control access to your sensitive content in SharePoint.

In planning mobile access to your SharePoint 2010 deployment, you should first consult the following article on the Microsoft Office 2010 Engineering Team Blog:

Configure SharePoint Server 2010 for Mobile Device Access

It will introduce the supported mobility scenarios for Office 2010. These mobility scenarios rely on support from SharePoint 2010 mobility, and this post describes how to setup your SharePoint environment so you can take advantage of mobile access.

Securing Access to Various Mobile Browsers

In Microsoft SharePoint 2010 today, you can enable or deny access to SharePoint based on a user’s mobile browser. This allows you to control which types of mobile devices can and cannot access SharePoint. This is configured through a simple customization of Out-Of-Box SharePoint. For the technical folks in the crowd, this is done by adding the appropriate section and user-agent string to the compat.browser file under the Virtual Directories folder for your specific web application.

There is a great blog post on the Microsoft SharePoint Team Blog found here (SharePoint 2010 and Apple iPad) that will guide you step by step on how to configure this.

Redirecting Users to the Full Web Interface on Mobile Browsers

As well, there are circumstances when the SharePoint 2010 mobile web interface is just not sufficient for your needs, either from a content collaboration point of view or from a security point of view. Through some simple code, you can modify the SharePoint redirect for mobile access to present the full web interface as opposed to the more limited mobile interface.

There is a great blog post by Waldek Mastykarz found here (Inconvenient SharePoint 2010 Mobile Redirect) that will walk you through the code and the modifications necessary to make this happen.

Special thanks to the authors of these articles, who spend their time helping the communicate understand how to better share and collaborate securely in Microsoft SharePoint.

-Antonio

Building a Custom Claim Provider to Manage Security Clearances

Microsoft SharePoint 2010, with its built-in support for retrieving trusted attributes about a user upon login (or what is commonly referred to as claims), can be used to authenticate users and authorize access to content. As I’ve written about previously, this allows businesses to implement new and interesting information protection policies. SharePoint also allows us to build and deploy custom claim providers that can retrieve attributes from a wide variety of sources and transform them in order to enforce specific policies within SharePoint. This article will walk through a simple example of building a custom claim provider and review some of the technical considerations that need to be taken into account.

A few weeks ago I gave a talk the Federal SharePoint User Group in Washington DC. Really good group there! Thanks to the 40 people or so that dialed into web cast for it. I`ve been traveling a lot the last few weeks with RSA 2012 and other shows, but I`ve finally gotten a chance to put the sample claim provider code I used in the presentation on our blog. Its a simple example and the process of building a claim provider is not too hard, but it is worth walking through the steps.

First I need to thank the excellent articles on Steve Peschka’s blog for the background and detailed information about developing for SharePoint using claims and federated identities. I highly recommend you check them out. The example here is based on some of those examples, but I’ve built this code with a different use case in mind and some additional detail in some of the steps in order to assist those developing custom claim providers for the first time.

Where do Custom Claim Providers Fit

In order to see how a custom claim provider fits into a SharePoint architecture that uses claims based authentication, you can refer to a previous article I`ve posted: An Architecture for Claims Based Authorization in SharePoint.

At a high level, here is what this could look like:

Using Claims for Authorization in SharePoint 2010

The Scenario – Setting It Up

In the Intelligence, Military and Government community, our customers tell us that managing an user’s security clearance is no trivial task. Users can have a wide variety of security clearances, and often there is a hierarchy associated with them. For example, if a user has Secret clearance, that typically permits them to access content that is classified as Secret and Confidential (with Confidential being the lower security clearance), but not Top Secret. If a user has Top Secret clearance, then they’re permitted to access content classified as Top Secret, Clearance and Confidential. Within a user’s identity however, customers often do not want to store multiple security clearances for them – they typically just want to store the user’s highest level of clearance, and have logic for determining all the content classifications they’re permitted to access executed somewhere else. This is the scenario that our example will follow.

A user will login to SharePoint and we’ll assume that a single security clearance (their highest level) is retrieved from an external trusted provider like ADFS 2.0. Our custom claim provider will then examine the clearance level returned and execute some simple logic to add any additional security clearances the user is entitled to.

Step by Step – Building a Custom Claim Provider for Security Clearance

1. Create a New Project
We start building a Custom Claim Provider by creating a new SharePoint 2010 project in Visual Studio 2010 (or later) and selecting an Empty SharePoint Project. Remember a custom claim provider will only be invoked in a web application that is configured for Claims Based Authentication, and Claims Based Authentication is only supported in SharePoint 2010 or later. Be sure to give your project a meaningful name, like ClaimProviderSecurityClearance.

2. Add the necessary References, Start a Class and Add Using Statements
You will need to add references to Microsoft.SharePoint (which will likely already be there) and Microsoft.IdentityModel. To do this, right click on References in the Solution Explorer pane, select Add References and selected the DLLs listed here. For the IdentityModel reference, you’ll need to browse to find it here:

\Program Files\Reference Assemblies\Microsoft\Windows Identity Foundation\v3.5\Microsoft.IdentityModel.dll.

Add a new class by right clicking on the project name in the Solution Explorer, selecting Add, then Class… In the Add New Item window, select C# Class and give it a meaningful name. A .cs file will appear in the main editing window, which will have some basic Using statements, and a skeleton class with a namespace that matches your project name.

Add the following Using statements to the ones already provided:

• using Microsoft.SharePoint;
• using Microsoft.SharePoint.Administration;
• using Microsoft.SharePoint.Administration.Claims;
• using Microsoft.SharePoint.WebControls;

Mine looks as follows:

3. Modify Your Class to Inherit from SPClaimProvider
You need to modify the class that you added to inherit from the base class SPClaimProvider. At this point, mine looks as follows:

4. Implement the Abstract Class
To get a skeleton implementation of the other class members, simply implement the abstract class by right clicking on base class SPClaimProvider in your .cs file and select Implement Abstract Class. This will result in a skeleton implementation of the following.

Members:

• FillClaimTypes
• FillClaimValueTypes
• FillClaimsForEntity
• FillEntityTypes
• FillHierarchy
• FillResolve(2 overrides)
• FillSchema
• FillSearch

Properties:

• Name
• SupportEntityInformation
• SupportHierarchy
• SupportResolve
• SupportSearch

As we move on, we’ll focus mainly on the implementation of the FillClaimsForEntity method and a number of helper methods.

5. Define the Properties for the Custom Claim Provider
Scroll down within your class and find where the implementation resides for the properties listed above. We need to set the appropriate properties to true depending on the behavior we want to achieve with our provider. The most important properties to consider for this example are Name and SupportsEntityInformation. The latter is important because you must set this property to true, if you are to implement the FillClaimsForEntity method and transform or augment the claims within the user’s identity. If set to false, then FillClaimsForEntity will not get called and you will not be able to manipulate the user’s claims. This section should look as follows:

The final 3 properties relate to the modifying the people picker used to select claims, users or groups in a claims based authenticated web application. Setting them to true is not strictly needed for this example, but if we want the claims defined by this provider to appear and interact appropriate with the people picker then they must be set to true and a basic implementation is required (which is shown below).

6. Create Static Properties for Name and Helper Functions
Next we need to create the following static properties in order to implement the provider’s Name, and the following helper methods to define the Claim Value and the Claim Value type:

Notice the URI used to define the claim value we’re working with (http://schemas.sample.local/clearance) which represents a security clearance. The URI can be anything you like, but it should follow a similar format for readability. The right most portion after the final / should be a meaningful name for the claim value because this is what will appear in the people picker in SharePoint. We have also defined the claim value’s type to be a string. This can be the same as a claim value that is returned from an external trusted provider like ADFS 2.0 if you wish to manipulate it after the user authenticates to ADFS 2.0. This example only defines 1 claim value, but if you were to work with multiple claim values within a provider you would replicate the following methods for each claim value you’ll be working with and give them each a unique name:

• ClearanceClaimType
• ClearanceClaimValueType

And then within the methods FillClaimTypes and FillClaimValueTypes you would have one claimTypes.Add() statement for each Claim Value you are working with.

7. Implement the Data Source and the Methods to Augment Claims
Up until this point, we were still putting in place the plumbing that is required by any custom claim provider you might build. Now we start adding our specific logic for managing security clearances in this simple case.

First we add our data source and another helper method as shown here:

Notice that for example purposes only, we’re using a simple array to define the data source and it contains only 4 possible security clearances defined simply as strings. In a real production environment, a more robust system may be used for storing and retrieving these types of attributes like MS SQL Server, an LDAP database, a PKI or Identity Management system.

The helper method shown DoesClaimValueAlreadyExist() is really useful for determining if a specific claim exists with a specific value in the user’s identity after authentication to a trusted external provider has already taken place. In this example, our external trusted provider is returning an attribute which defines the user’s highest security clearance. If the claim exists with the specified value, it simply returns a boolean. It is used heavily in the next step.

Next we’ll implement FillClaimsForEntity() where are logic for managing clearances exists. It will look as follows:

As you can see, the logic here is quite simple. Just check what their highest level of clearance is, and based on that add all the lower level clearances the user is entitled to. This logic could certainly get more complex, especially if we take things like Caveats into account or what department a user belongs to.

8. Implement People Picker Related Methods
In this example, we are not customizing the experience within the people picker so we are only including a very basic implementation here. If your business requires that the people picker be customized (because the experience is not great with claims out of the box) then you would do this by implementing a custom claims provider – look for more on that in a future post. Here is what it looks like without any customization and, although usable, it has many issues that I’ll get into in another post as well:

A minimal implementation is required in order to simply have the Clearance claim included in the people picker when it is used. The implementation would look like this:

The specific purpose of each method is as follows, related in each case specifically to the claims defined in this provider:

• FillEntityTypes – Set of possible claims to display in the people picker
• FillHierarchy – Determine hierarchy for displaying claims in the people picker
• FillResolve(2 overrides) – Logic for resolving claims specified in the people picker
• FillSchema – Specifies the schema that is used by people picker to display claims/entity data
• FillSearch – Fills in search results in people picker window

9. Define the Feature Receiver that Will Deploy the Custom Claim Provider
Custom claim providers are deployed to SharePoint 2010 as farm level features so they must be built within the context of a SharePoint feature receiver. To do this, we’ll add a new class to the project as we previously did (right click the project in the Solution Explorer, select Add, then Class and select a C# class).

The class will need to inherit from SPClaimProviderFeatureReceiver and it should look exactly as follows (with your namespace and class name):

Next we’ll need to right click on Features in the Solution Explorer and select Add Feature. You’ll see a file called Feature1.Feature. Here you must select Farm in the scope drop down and click Save. Then in the Properties pane on the right side you’ll need to set the Receiver Assembly and Receiver Class properties correctly.

This should allow the feature receiver to be deployed correctly to your SharePoint server from within Visual Studio. If you perform the deployment, then go to Central Admin and Manage Farm Features you’ll see your Custom Claim Provider listed and active by default.

Congratulations! You’ve just built and deployed your first Custom Claim Provider.

Testing Your Claim Provider

Remember, this claim provider is dependent on a few things, namely:

• One of your SharePoint 2010 web applications must be enabled for Claims Based Authentication
• A ‘clearance’ claim must be first returned from an external trusted provider like ADFS 2.0

If you are using ADFS 2.0, remember you need to first map the expected claims into SharePoint using PowerShell. If this is not done, SharePoint will simply ignore any incoming claims that have not been mapped.

If you don’t have ADFS 2.0 in place returning such a claim, you can simply add 1 more claims.Add() statement near the beginning of the FillClaimsForEntity() method that starts the user off with one of these particular claim.

Then you simply login to your SharePoint web application that is claims enabled and see which claims have been retrieved.

When you login, you’ll need a way to see what claims have been returned for that user. To help with this, we highly recommend installing the following Claim Tool for SharePoint. It will allow you to quickly view what claims SharePoint has retrieved for the user in question. I have the web part added at the site level so I see it as soon as I login and its invaluable for debugging.

Conclusion

Building custom claim providers is not difficult and, because they run as features on the SharePoint server at the farm level, they can help to implement some really interesting policies related to authenticating identities and authorization.

Once a user has signed in and their claims are retrieved, SharePoint 2010 does a great job of enforcing access control on documents/items to which claims have been assigned. Of course a user must have those claims as part of their identity to gain access to a document or item with the assigned permission level. Transforming claims in this way after they have been retrieved from ADFSv2 can allow you to implement some very robust access control policies in SharePoint. Applying those claims with permission levels to documents and items in SharePoint is still a manual and labor intensive task that can be very error prone – for more information on how the TITUS SharePoint Security Suite can automatically assign such access control policies at a fine grained level in SharePoint please read the white paper Microsoft SharePoint Security – Harness the power of claims to protect information or check out the video.

Enjoy.
-Antonio

Using AD Groups in a Claims Based Web Application

I ran across an interesting little side effect of altering my claims enabled web application in SharePoint 2010 the other day I thought would be useful for others to know about. The situation has to do with accessing AD Groups from within the SharePoint people picker in a claims enabled environment.

Initially one of my SharePoint web applications was configured to allow authentication either through NTLM or through a Trusted Claims Provider (which was ADFS 2.0 sitting in front of AD of course). I could select which method I wanted to use when I navigated to the site through the default sign in page which presented a drop down list of the 2 authentication providers. At any time I could authenticate through NTLM or through the claims provider. This was all standard stuff so far.

I decided that I should clean up this web application since I was only using claims based authentication, and I removed the option for NTLM authentication. This just made the environment a little cleaner from a usage and demo perspective.

Then I logged into my web application through the ADFS 2.0 provider and proceeded on with additional work. I was configuring an existing library with a new metadata column – it was a People and Group column. My intention was to use this column in a demonstration where I was selecting groups were associated with specific items in the library. I wanted to be able to specify a different group for different documents in the library. In particular I wanted to use Active Directory groups and I already had a number of groups setup. So, I add my column and tried to select the AD groups I already had been using for some time. It turned out that my SharePoint people picker could no longer resolve the groups that I was searching for.

I checked over my AD installation. I checked that my groups were configured correctly. But nothing seemed out of the ordinary, nor would any changes here to improve the situation. Then I noticed that my people picker was missing the Active Directory node – it looked like this:

I was no longer able to search against any Active Directory groups!

So, with my upcoming demonstration looming, to try to resolve this I returned to Central Admin and the Manage Web Application page. I reconfigured the authentication providers for this web application so that once again I could sign in through either NTLM or my trusted ADFS 2.0 provider. I logged in once again using the ADFS 2.0 provider, went to add a group to my metadata column an I could find my AD groups again. My people picker now looked as follows:

Notice the Active Directory node on the left side. I could now find and select my ‘JointChiefs’ group and add it to my column (note I need to choose the one on the right side that is under the Active Directory heading.

So, it turns out that even if I’m always signing into SharePoint through my ADFS 2.0 claims provider, I need NTLM or Kerberos configured as an authentication provider for my web application in order to access Active Directory entities like groups in the SharePoint people picker. Please keep in mind that this is without any customization of the people picker using a custom claim provider.

Hope this helps someone that might run into the same situation.
– Antonio

How do you Check Multiple Groups to Enforce Security in SharePoint 2010?

Implementing claims based authorization in SharePoint 2010 provides great alternatives to using security groups in order to control access to sensitive content in SharePoint.  Traditionally, security groups have been used to restrict access to content or to enforce a role based security mechanism.  However, organizations are quickly finding that security groups, whether they are SharePoint groups or Active Directory groups, do not scale well in large enterprise environments.  Many enterprises already have large numbers of groups deployed, so how can those organizations still make use of those groups to enforce advanced security policies without complicating group management further?  As well, how can they check membership to multiple groups in order to allow access to sensitive content? This article focuses on using claim rules in Active Directory Federation Services version 2 (ADFSv2) as an efficient mechanism to enforce security policies in SharePoint based on group membership.

The Challenge with Security Groups

We’ve worked with several customers that need to enforce security policies in SharePoint which are based on a user’s membership to one or more groups.  Often, large enterprises have large numbers of existing groups, typically numbering in the thousands which have been created over a period of years, and creating new groups in order to manage security is not an option because the existing set is already difficult to manage.  They’re usually looking for a better solution.  We have seen lately that some organizations with very sensitive content have policies that involve allowing a user access to a particular item, list, library or site in SharePoint if that user belongs to more than 1 group – for example, I mean a scenario where a user is permitted to access DocumentX if they belong to both GroupA and GroupB.

SharePoint does not easily support such a requirement.  By default, SharePoint supports an OR relationship between all users/groups that have been given access to an item.  So, if today I give GroupA and GroupB access to a SharePoint item, a user needs to belong to only one of the groups in order to gain access.  Currently, to enforce such a policy in SharePoint requires you to manually create a third group, GroupC, which contains only the users that belong to both GroupA and GroupB.  These groups are sometimes called “Intersecting Groups” because they represent the intersection of GroupA and GroupB.  We can easily see how this does not scale:

• In a large environment, with many existing groups and many sites/lists/libraries/items with varying security requirements, you may need to manually create a very large number of groups (and manually determine what the intersection is)
• If the security policy requires that a user belongs to 3, 4 or more groups the problem only becomes more difficult to manage with manually
• The number of groups keeps increasing and the problem of managing a large number of groups only gets worse
• What happens when the membership of GroupA or GroupB change, perhaps because a user changes roles or teams, you will need to manually modify the membership of GroupC

ADFSv2 along its support for Claim Rules gives us a much more scalable solution to enforce such security policies in SharePoint.  For more background on Claim Rules in ADFSv2 and the Claim Rule Language, please see the following previous articles:

• Claims Based Security in SharePoint 2010 with ADFSv2 – Part 1: Claim Rules

• Claims Based Security in SharePoint with ADFSv2 – Part 2: Claim Rule Language

Checking Membership to a Single Group

In ADFSv2 we can easily create a claim rule using a ‘Group Membership’ rule template – this rule would check a user’s membership to a specified AD group and use that as a condition when issuing a claim. Such a rule would be executed for each user at the time of authentication (ie. at login time) which means that a policy based on this rule will always be up to date and using the latest group membership from Active Directory.

You can create this rule by following these steps in ADFSv2:

• Click Trust Relationships > Relying Party Trusts on the left side of the ADFSv2 Console
• Right click the appropriate Relying Party Trust and select the Edit Claim Rules… menu item
• Click the Add Rule… button
• A wizard appears – in the dropdown list select “Send Group Membership as a Claim”; click Next
• Give the rule a meaningful name
• Click Browse to select the appropriate AD group you wish to check for membership
• Type in the name of the group and click Check Names – you may be required to login to the AD domain; I selected a group I had pre-created called “Finance”
• Select the Outgoing Claim Type (the claim that will be issued) and specify the Outgoing Claim Value; the Outgoing Claim Type must be a claim type that has already been created in the list of Claim Descriptions, and the Outgoing Claim Value can be any string – I selected an outgoing claim called “policydecision” and specified the value “true”

NOTE: using the ‘Group Membership’ rule template only allows you to check for membership to 1 group at a time.  The wizard interface will look like it allows you to specify more than one group, but it will ultimately restrict each claim rule to only checking 1 group.

Let’s look at the Claim Rule Language for this example:

c:[Type == ”http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid”, Value == “S-1-5-21-563680538-1201701862-760492540-1109”, Issuer == “AD AUTHORITY”]

=> issue(Type = “http://schemas.sp.local/policydecision”, Value = “true”, Issuer =c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

So, this rule ultimately says if the user logging in belongs to the AD group Finance, then issue the claim policydecision=true.  You’ll notice that even though I selected “Finance” as the AD group to check against, the rule converted that to the group SID “S-1-5-21-563680538-1201701862-760492540-1109”.  group SIDs are immutable, meaning once they are created they do not change, so this is fine.  The only issue this might cause is readability of the rule language, but we can work around that.

Checking Membership to Multiple Groups

But what if you want to check 2 or 3 AD groups for membership and only if a user belongs to all of them  issue the claim policydecision=true?  This can easily be done by creating a custom claim rule that replicates the condition in the claim rule above and separates the conditions with &&.  Since the rule converts the group name to group SIDs you’ll need to get the SIDs for all the groups you wish to check.

You can do this using 1 of 2 methods:

• Access ADSIEdit for your Active Directory, navigate to the appropriate groups, find the objectSID attribute for each group and note down their values
• Or, if you don’t have ADSIEdit access to AD, create a claim rule using the “Send Group Membership as a Claim” rule template for each group in question and then copy and paste the text from the resulting claim rule language (remember for each rule created you can click the View Rule Language… button) – you can delete these rules later

Once you have the group SID for each group, create a Custom Claim Rule and enter the following:

c:[Type == ”http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid”, Value == “S-1-5-21-563680538-1201701862-760492540-1109”, Issuer == “AD AUTHORITY”]

&& c1:[Type == ”http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid”, Value == “S-1-5-21-563680538-1201701862-760492540-1110”, Issuer == “AD AUTHORITY”]

&& c2:[Type == ”http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid”, Value == “S-1-5-21-563680538-1201701862-760492540-1111”, Issuer == “AD AUTHORITY”]

=> issue(Type = “http://schemas.sp.local/policydecision”, Value = “true”, Issuer =c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

This claim rule will now check membership to 3 different AD groups, and only if the user belongs to all 3 groups will the claim “policydecision” with the value of “true” be returned as an outgoing claim.  Be sure to replace the group SID values with the respective values for the groups you have in mind – it happened that the 3 groups I created and used all had sequential group SID values, but yours many not.

Within SharePoint 2010, if a claim of type “http://schemas.sp.local/policydecision” with a value of “true” is assigned to an item with the permission level of Full Control, then the user will only gain Full Control access to this item if they belong to all 3 groups.

Benefits of Group Membership Rules in ADFSv2

This is in fact a very efficient way of enforcing such a security policy within SharePoint 2010:

• Every time the user logs into SharePoint, group membership is validated, so policies are always using the latest information to determine what outgoing claims are returned
• No manual groups to create or maintain, especially as memberships to existing groups changes
• Only 1 claim is added to the outgoing claim set for each rule – when a user logins, ADFSv2 by default retrieves the SIDs for the groups a user belongs to as part of the incoming claim set

Note:  This solution will be limited to Active Directory groups because ADFSv2 doesn’t have access to SharePoint groups.

Using TITUS Metadata Security Claims Edition with Group Membership

TITUS Metadata Security Claims Edition can automatically apply group membership policies like these to documents, items and folders in SharePoint 2010 using claims.  TITUS Metadata Security has a great feature where the values of metadata columns can be used to dynamically set claims on items or folders as permissions with specific permission levels.

For example, let’s consider a situation where we have financial data in a SharePoint library that is particularly sensitive and where Contribute access is only given to members of the Audit Team, who are Senior Managers, and who are part of the Finance Department.  We can enforce such a policy automatically by creating 3 metadata columns for the library with the columns named Team, Role and Department. These columns can represent the 3 groups that users must belong to in order to access particularly sensitive content.  Then, in TITUS Metadata Security a policy can be created which reads as follows:

Claim Type:                         http://schemas.sp.local/policydecision

Value:                                   {Team}{Role}{Department}

Permission Level:             Full Control

So, an item that requires a user to be part of the Audit Team, to be a Senior Manager and to be part of the Finance Department in order to access it, can set the 3 columns as such in SharePoint.  TITUS Metadata Security will then automatically generate the appropriate claim by taking the column data specified by the policy and concatenating those values together to form the claim value.  TITUS Metadata Security will then apply the claim type with the generated value as permission to the item.  It will apply this claim to existing content in SharePoint, as well as when new content is added or when content changes (even when metadata changes).

A corresponding claim rule must also be created in ADFSv2 that is similar to the one listed above, but with a slight change, as follows:

c:[Type == ”http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid”, Value == “S-1-5-21-563680538-1201701862-760492540-1109”, Issuer == “AD AUTHORITY”]

&& c1:[Type == ”http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid”, Value == “S-1-5-21-563680538-1201701862-760492540-1110”, Issuer == “AD AUTHORITY”]

&& c2:[Type == ”http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid”, Value == “S-1-5-21-563680538-1201701862-760492540-1111”, Issuer == “AD AUTHORITY”]

=> issue(Type = “http://schemas.sp.local/policydecision”, Value = “AuditSeniorManagerFinance”, Issuer =c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

Since the group SIDs must be provided in the claim rule and they can only apply to specific named groups, we can simply include the group names as the value right in the issuance statement of the claim rule as shown.  TITUS Metadata Security can also allow you to specify metadata conditions so that such claims are only generated and applied under specific metadata-based conditions.

TITUS Metadata Security for Microsoft SharePoint allows you to secure your sensitive data within SharePoint.  Security policies can be based on users, security groups, trusted claims or some combination of the three.  Policies can be applied based on existing security groups dynamically and automatically in very secure environments, without increasing the management overhead of additional security groups.

-Antonio

Claims Based Security in SharePoint with ADFSv2 – Part 2: Claim Rule Language

In a recent post I introduced the concept of claim rules within Microsoft Active Directory Federation Services 2.0 (ADFSv2) and the templates it provides.  Claim rules can be used to easily evaluate, transform or augment claims before they are returned to a relying party application like SharePoint.  In this post, the second in the series, we dive into ADFSv2’s Claim Rule Language and how it can be used to issue claims under more specific conditions, retrieve attributes from external data sources and implement some unique scenarios.

 

For an introduction to claim rules or some background on the template based rules built into ADFSv2, see the earlier blog post in this series:

Claims Based Security in SharePoint 2010 with ADFSv2 – Part 1: Claim Rules

This post is only going to deal with ‘issuing outgoing claims’.  These are claims that ADFSv2 will return to a relying party application.  It is important to note that ADFSv2 has a set of incoming claims (and those can be configured) that our claim rules will refer to as part of their conditions, and it has a set of outgoing claims that will be returned to SharePoint in this case.  Incoming claims can be processed as part of the claims pipeline, but those are not dealt with here in great detail.  For more background on the claims pipeline please see the following article.

Show me the Language for my Rule

A nice option in ADFSv2 is that after you’ve created a claim rule using a template, when you edit that rule there is a button available called “View Rule Language”.  This will bring up the associated claim rule language script for that rule.  This helps in learning the language, and provides a good starting point for new rules – you can copy the text from these rules and paste into a new custom rule.

When to Use a Custom Rule

When adding a new claim rules, the last option available in the Claim Rule Template dropdown list is “Send Claims Using a Custom Rule”.  Selecting this option allows you to specify very specific conditions for this rule using the built in claims rule language.  This option allows you to create rules that deal with many unique scenarios including:

• Sending claims from a SQL attribute store
• Sending claims from an LDAP attribute store using a custom LDAP filter
• Sending claims from a custom attribute store
• Sending claims only when 2 or more incoming claims are present
• Sending claims only when an incoming claim value matches a complex pattern
• Sending claims with complex changes to an incoming claim value
• Creating claims for use in later rules
• Creating rules that depend on membership to more than one AD group

Rule Structure

Every claim rule, whether it’s custom or template-based, is made up of 2 parts:

• zero or more condition statements
• one issuance statement

A claim rule typically has the following structure:

c:[condition]

=>issue(type=”…”,  value =”…”);

…where type and value are the properties for the new claim you are issuing.

• Every claim rule must have at least one issue statement.
• Condition statements are optional, but not including one means the rule will be executed on every incoming claim.
• If a condition is included in a rule and it evaluates to true, then the issuance is executed.  If the condition is false then the issuance is not executed and the rule engine moves onto the next claim rule.
• Every rule will be processed for every incoming claim.

The letter “c” at the beginning of the rule represents a variable that contains the claim evaluated.  This can be reused later in the issuance statement.  Multiple conditions can be included in the same rule separated a logical operator; however each condition must start with a unique variable.

Here is an example of a simple custom claim rule.

c:[type == “http://schemas.sp.local/clearance”, value == “secret”]

=>issue(type =” http://schemas.sp.local/policydecision”, value=”true”);

This rule will evaluate the following condition:  if a claim of type “http://schemas.sp.local/clearance” exists in the set of incoming claims and if it has a value of secret.  If true, then this rule will issue a new claim of type “http://schemas.sp.local/policydecision” with a value of true.

The value of a claim being issued can be static text (as in the examples above), or it can be part of the value of an incoming claim that was used in the condition statement.  This can be done by using the variable that was assigned in the condition statement, for example:

c:[type == “http://schemas.sp.local/clearance”, value == “secret”]

=>issue(type =” http://schemas.sp.local/accesslevel”, c.value);

Condition Properties

The following properties can be validated as part of a condition:

• Type
• Value
• Issuer
• OriginalIssuer
• ValueType

Here is another example:

c1:[Type == “http://schemas.sp.local/ExportControl”]

=>issue(Type =” http://schemas.sp.local/policydecision” value=”true”);

In this case we check the condition:  if a claim of type “http://schemas.sp.local/ExportControl” exists (regardless of its value).  If this claim type simply exists then a new claim of type =  “http://schemas.sp.local/policydecision” and value=”true” will be issued as an outgoing claim.

You can even have more than 2 properties as part of the condition all separated by comma, for example:

c1:[Type == “http://schemas.sp.local/ExportControl”, value=”T.12”, issuer==”ADMINISTRATOR”]

=>issue(Type =” http://schemas.sp.local/policydecision” value=”true”);

Operators

There are several operators available in the language, that can be used both as part of the condition and as part of the claim being issued, to help implement more interesting scenarios.

Logical AND – You can use multiple conditions separated by a logical AND operator, which is written in the rule as &&.  The following is an example:

c1:[type == “http://schemas.sp.local/ITARAuthorized”, value == “Yes”]

&&  c2:[type == “http://schemas.sp.local/currentLocation”, value == “USA”]

=>issue(type = “http://schemas.sp.local/policydecision”,  value = “true”);

We’re AND’ing 2 conditions together:  if the claim “http://schemas.sp.local/ITARAuthorized” has the value Yes AND the claim “http://schemas.sp.local/currentLocation” has the value “USA”, then the claim “http://schemas.sp.local/policydecision” will be issued with a value of “true”.  You can AND more than 2 conditions as well, as long as they each have a unique variable.

Logical OR – There is no logical OR operator. If an OR is needed between conditions then it’s recommended that you create multiple claim rules, one for each condition.  For example, if you want to implement a rule where if [type == “http://schemas.sp.local/ITARAuthorized”, value == “Yes”] OR [type == “http://schemas.sp.local/currentLocation”, value == “USA”] then issue a claim, you would create the following 2 rules:

Rule 1

c:[type == “http://schemas.sp.local/ITARAuthorized”, value == “Yes”]

=>issue(type = “http://schemas.sp.local/policydecision”,  value = “true”);

Rule2

c:[type == “http://schemas.sp.local/currentLocation”, value == “USA”]

=>issue(type = “http://schemas.sp.local/policydecision”,  value = “true”);

EXISTS Function – There is an EXIST operator that can be used as part of a conditional statement which will check for the existence of a claim within the incoming claim set and, regardless of how many instances of the specified claim exist, the rule will issue only one instance of an outgoing claim.  Here is an example:

EXIST([type==”http://schemas.sp.local/clearance”])

=>issue(type = “http://schemas.sp.local/policydecision”,  value = “true”);

In this case, using the EXIST operator will cause the ‘policy decision’ claim will be issued only once regardless of how times the ‘clearance’ claim is found in the incoming claim set.  This is different from the following statement:

c:[type==”http://schemas.sp.local/clearance”]

=>issue(type = “http://schemas.sp.local/policydecision”,  value = “true”);

…where the ‘policydecision’ claim will be issued once for each instance of the ‘clearance’ claim. So if you have 2 instances of ‘clearance in the incoming claim set, you’ll have 2 instances of the ‘policydecision’ claim in the outgoing claim set.

NOT EXISTS Function – A really interesting operator is the NOT EXISTS operator, which will evaluate a condition to true if the specified claim does not exist in an incoming claim set.  Here is an example:

NOT EXISTS([type==”http://schemas.sp.local/clearance”])

=>issue(type = “http://schemas.sp.local/policydecision”,  value = “false”);

In this case, if there is no instance of the ‘clearance’ claim in the incoming claim set, then the ‘policydecision’ claim will be issued with a value of “false”.  This is very useful in situations where your SharePoint 2010 server may be federated with a partner company and you cannot be guaranteed that all user’s logging in will even have the appropriate claim types in their incoming set, regardless of what values they may have.  This operator allows you, in these circumstances, to restrict users even further until they gain the appropriate attributes or clearance levels in their identity.  For example, you could have a set of claim rules that pertains to external users from a partner organization (Organization X) which checks their access level and depending on that value maps them to an internal level of access, but if they do not have the access level claim at all then they receive very restricted access:

Rule 1:

c:[Type == “http://schemas.sp.local/AccessLevel”, value=”A1”, issuer==”ORG_X_ADMIN”]

=>issue(Type =” http://schemas.sp.local/internalaccess” value=”high”);

Rule 2:

c:[Type == “http://schemas.sp.local/AccessLevel”, value=”A2”, issuer==” ORG_X_ADMIN”]

=>issue(Type =” http://schemas.sp.local/internalaccess” value=”moderate”);

Rule 3:

c:[Type == “http://schemas.sp.local/AccessLevel”, value=”A3”, issuer==” ORG_X _ADMIN”]

=>issue(Type =” http://schemas.sp.local/internalaccess” value=”low”);

Rule 4:

NOT EXIST([Type == “http://schemas.sp.local/AccessLevel” issuer==” ORG_X _ADMIN”]

=>issue(Type =” http://schemas.sp.local/internalaccess” value=”none”);

Concatenating Values – when issuing a claim as part of a rule, it is possible to concatenate values from the incoming claims used in the conditions, or to concatenate a claim value with static text.  This is done with the + operator.  For example:

c1:[type==”http://schemas.sp.local/role”]

&& c2: [type==”http://schemas.sp.local/office”]

=>issue(type = “http://schemas.sp.local/responsibility”,  c1.value + “ “ + c2.value);

As a result, if role=”Regional Manager” and office=”New York” then the outgoing claim will be set to:

type = “http://schemas.sp.local/responsibility”, value=”Regional Manager New York”

This can also be very useful for creating claims, and ultimately access control policies, that compound the values of one or more other claims.  For example, if a user is to be granted a certain level of access to a document if they have a clearance of “secret” and a caveat of “+a’, a different level of access if they have a clearance of “secret” and a caveat of “+b”, and yet another different level of access if they have clearance of ‘top secret’ (regardless of caveat) this can be implemented by concatenating claim values together in this manner:

Rule 1:

c1:[type==”http://schemas.sp.local/clearance”, value==”secret”]

&& c2: [type==”http://schemas.sp.local/caveat”]

=>issue(type = “http://schemas.sp.local/accesslevel”,  c1.value + “ “ + c2.value);

Rule 2:

c1:[type==”http://schemas.sp.local/clearance”, value==”top secret”]

=>issue(type = “http://schemas.sp.local/accesslevel”,  c1.value);

 

• if Clearance=”secret” and caveat=”+a”… then accesslevel = “secret+a” and user gets read access to a document

• if Clearance=”secret” and caveat=”+b”… then accesslevel = “secret+b” and user gets contribute access to a document

• if Clearance=”top secret” and regardless of caveat (this could potentially be a 2^nd rule)… then accesslevel = “top secret” and user gets full control access to a document

And this can extend to more than 2 claim values, and more than 2 rules to create more complex policy decisions.  SharePoint can ultimately apply the matching claims to documents and items with the permission level mentioned in the last example, and if users have the appropriate claims when they log into SharePoint they’ll receive that level of access over that content.

Multiple Instances of a Claim

As well, if there is more than one instance of an incoming claim, the rule will be processed for every instance.  For example, if I have the following as my incoming claims (which is a valid set of claims because it can denote this user is entitled to resources classified as any of these clearances):

Type=http://schemas.sp.local/clearance                              Value=Confidential

Type=http://schemas.sp.local/clearance                              Value=Secret

Type=http://schemas.sp.local/clearance                              Value=Top Secret

Every claim rule will be processed for every instance of http://schemas.sp.local/clearance.  When claims are assigned to documents and items in SharePoint with permission levels, as long as the user logging in has 1 claim in their identity which matches 1 claim assigned as a permission to the document then the user will get access to the item at the assigned permission level.

Summing it up…

Again, once a user has signed in and their claims are retrieved, SharePoint 2010 does a great job of enforcing permissions on documents and items to which claims have been assigned with a permission level. Of course a user must have those claims as part of their identity to gain access to a document or item with the assigned permission level. For sophisticated policies, ADFSv2 does provide some great options using the claim rule language to augment or transform claims before they are returned to SharePoint.  This ultimately allows you to defined detailed policies with very specific conditions that are enforced in SharePoint.

Applying those claims with permission levels to documents and items in SharePoint is still a manual and labor intensive task that can be very error prone – for more information on how the TITUS SharePoint Security Suite can automatically assign such access control policies at a fine grained level in SharePoint please read the white paper Microsoft SharePoint Security – Harness the power of claims to protect information or check out the video.

Fail Safe Security for Microsoft SharePoint

Microsoft SharePoint is used in many highly secure environments around the world that deal very sensitive information – information that is considered ’secret’ or ‘top secret’ and where security of that data is critical to not only business but also to national security. These deployments exist primarily in military and government installations, or as part of the intelligence community. In these SharePoint deployments, its extremely important that security and access control policies be configured in such a way that they “Fail Safe”.

The concept of “Failing Safe” means that if the security system which implements the access control policies fails, for whatever reason, that sensitive information will automatically have the most restrictive access rights automatically applied. Therefore, in these cases, if such a system failure occurs then the sensitive information that is being protected is not left open and in the clear, allowing non-authorized users to access it.

Examples of an access control policy system failing could be an authorization server going down, it could be an inadvertent reboot of a server, or it could even be an unauthorized user gaining access to the environment and interrupting communication between the authorization system and the content management system (SharePoint). There are many such examples. Hardening critical infrastructure and protecting it against all possible forms of attack or circumstances that might arise is a very difficult task that must be performed. However, you also want to ensure that you look at this problem from the point of view of: if all else fails, then access to my sensitive information will revert back to the most restrictive access rights possible so that my sensitive data is not inadvertently released.

TITUS Metadata Security for SharePoint uses trusted claims about a user, and combines them with document metadata to ensure that the right people are accessing the right information in SharePoint. TITUS Metadata Security automatically applies fine grained access control to SharePoint content using the SharePoint permissions system. This has the advantage of enforcing the access control policies that administrators or site owners configure on all the mechanisms that information workers can use to access content within SharePoint, including the SharePoint web view, the explorer view, search, FAST search, the client object model, the server object model and any web services that may be deployed. With TITUS Metadata Security, policies are dynamically enforced, so that as a user’s identity changes or as metadata changes, security policies are automatically applied and user’s are only accessing the content they are permitted to access.

TITUS allows you to set the default permissions on all content within SharePoint to the most restrictive access rights possible. Then when defining access control policies and enforcing those policies with TITUS Metadata Security, TITUS will simply add the appropriate access rights for specific users, groups, or users with specific claims to only gain access to sensitive content that they are permitted to access . This allows Microsoft SharePoint to “Fail Safe” so that if a malicious user or a failure in process subverts the access control policy system, that your sensitive information will revert back to its default inherited SharePoint permissions (the most restrictive access rights possible) and still remain secure!

There are several other systems on the market which implement access control policies or entitlement management in Microsoft SharePoint. However, these systems often require that default permissions on all content be initially configured to the most open access rights possible. The issue here becomes that if that access control system were to be subverted or fail, for whatever reason, and if SharePoint then reverts back to its default inherited permissions then all content including your most sensitive content will be inadvertently leaked. TITUS Metadata Security for SharePoint is the only leading fine grained security system for Microsoft SharePoint that allows SharePoint to”Fail Safe”.

TITUS Metadata Security for SharePoint allows organizations to leverage all of the benefits of user claims and document metadata to secure their sensitive information in SharePoint. It ensures that the right people are accessing the right information and it allows Microsoft SharePoint to implement Fail Safe Security so that sensitive information remains secure in all circumstances.

-Antonio

Claims Based Security in SharePoint 2010 with ADFSv2 – Part 1: Claim Rules

Previously, we’ve talked about how using trusted attributes of a user’s identity (or claims) along with document metadata is a very robust way of enforcing security policies within Microsoft SharePoint 2010. This article reviews another important tool that can be used to configure security policies for SharePoint:  Claim Rules.

In general, claim rules can be used to centrally evaluate, transform or augment claims before they are returned to a relying party application like SharePoint. Microsoft Active Directory Federation Services version 2.0 (ADFSv2) can act as a trusted identity provider to SharePoint and other relying party apps.  It provides a great interface with templates for creating and editing claim rules as part of its management console.  As well, it provides a ‘claim rule language’ that can be used to configure detailed policies with very specific conditions. This allows us to configure specific claims to be retrieved under very specific conditions, and thereby enforce very specific security policies for authentication and authorization.

This series of articles talks in detail about how to use this mechanism to enforce dynamic access control policies within SharePoint 2010 and, it illustrates how these policies relate to particular industries and regulations in SharePoint.

This article assumes an in-depth level of knowledge related to configuring SharePoint with Claims Based Authentication using ADFSv2.  For additional background on these topics please see the following article: An Architecture for Claims Based Authorization in SharePoint.

SharePoint 2010 can be configured to connect to a trusted identity provider like ADFSv2 to authenticate a user at sign-in time.  This is called Claims Based Authentication.  Under such a configuration, when a user signs into SharePoint, it will communicate with ADFSv2 passing it the user’s credentials.  ADFSv2 will then authenticate the user against Active Directory.  Before this happens, ADFSv2 will have been configured to trust the SharePoint 2010 server (the relying party) that is connecting and, as part of that trust relationship, ADFSv2 will have also been configured with 1 or more claim rules.  After the user is authenticated, ADFSv2 will apply the configured claim rules to the incoming claims in order to transform or augment them before they are issued and returned to SharePoint.

Configuring Claim Rules

ADFSv2 can be configured to accept incoming claims as well as issue outgoing claims.  In either case, trust needs to be configured between ADFSv2 and the calling app.  For incoming claims, the trust relationship in the ADFSv2 management console is referred to as the “Claims Provider Trust”.  For outgoing claims, or claims that ADFSv2 issues to a relying party, the trust relationship is referred to as the “Relying Party Trust”.  The important point here is that claim rules are configured as properties of these “trusts”.

ADFSv2 Management Console

ADFSv2 can be configured with one or more trusts (one for each calling application), and each trust can have one or more claim rules. When configuring a trust for SharePoint, you will need to provide the realm of the SharePoint server. ADFSv2 will use the realm passed to it in order to map a particular request to a particular trust that’s been configured.  For more information on configuring the realm, see the following:  Configuring the Realm for SharePoint 2010 and ADFSv2 to Retrieve Claims.

Once the trust is configured for the particular SharePoint server, to create a claim rule for that trust, perform the following steps:

• In the ADFSv2 Management Console, click Relying Party Trusts in the tree at the left side
• Right click on the particular trust which pertains to the SharePoint server you’re working with
• Click the Edit Claim Rules menu
• Ensure that you have the Issuance Transform Rules tab selected (the first tab)
• Click the Add Rule button and follow the instructions in the wizard – it is quite easy to use
• Keep in mind that the claim rules will be executed in the order listed. This can be important, especially if you have one claim rule acting on the claims issued by another rule. You can use the arrows on the right side of the Edit Claim rule window to change the order and get the desired output.

Once you’ve configure a set of claim rules for a particular trust, unfortunately they cannot be reused on another trust. If you must reuse the same claim rule(s) with more than one trust, you’ll need to manually recreate them. We’re focusing on enforcing security policies within SharePoint, so this particular article will focus only on claim rules configured for a Relying Party Trust which issues outgoing claims to SharePoint. From this point forward, the article will refer to SharePoint as the relying party, but please keep in mind that any relying party can be configured and used with the same types of claim rules.

Again, when a user signs into SharePoint, SharePoint will call its configured trusted identity provider, ADFSv2 in this case, and ADFSv2 will authenticate the user against its directory or database. Then ADFSv2 will execute the claim rules that have been configured with the particular trust for the calling SharePoint server. These particular claim rules will be used to determine which attributes are ultimately issued to (ie. returned) to SharePoint.

Claim Rule Templates

Claim rules will be used to determine which attributes are ultimately issued as outgoing claims (ie. returned) to SharePoint. These rules can be quite simple – for example, they can simply retrieve specific LDAP attributes from Active Directory and return them to the connecting SharePoint server as SAML claims. They can also be more complex, and we’ll see some examples of that later. The ADFSv2 management console provides 4 templates and an easy to use wizard for configuring rules. For many security policies, these templates are quite sufficient for achieving a policy’s intended purpose. These templates are:

1. Send LDAP Attributes as Claims

• Probably the simplest type of rule, it can be used to retrieve user attributes from an LDAP directory and issue them as outgoing claims to SharePoint.
• It can be used to perform a simple mapping of attributes if required, from an LDAP attribute name to perhaps a different name (or claim type) that SharePoint is expecting. For example, a claim rule could retrieve the standard LDAP attribute ‘organizationStatus’ and map it to the claim type ‘EmployeeStatus’ if that’s more appropriate for the intended user experience within SharePoint.
• Multiple claims can be retrieved or mapped with a single rule.
• Performance can be somewhat affected by this type of claim rule due to the account look up that must occur. However, for all practical purposes the performance impact appears to be minimal for each individual request.

2. Send Group Membership as a Claim

• This claim rule will check to determine if the user is a member of a specific AD group and if so, it will issue a specified claim with a specified value. This can be very helpful if you already have security groups in place and want to leverage them to enforce claims based authorization policies in SharePoint.
• The unfortunate thing about this template is that each rule will only check membership to 1 group. You can create multiple instances of this type of rule for the same trust, and within each rule check membership to a different group so that a particular claim is issued in each case. However, if you want to enforce policies where a user must belong to multiple groups in order to access content within SharePoint, then a more sophisticated solution is needed – Please see Part 3 of this blog series for an example of how to accomplish this with the Claim rule Language.
• As well, this claim rule does not support SharePoint groups, only Active Directory groups. To check membership to SharePoint groups, you must create a custom claims provider that runs on your SharePoint server… but that is for another day.
• One positive thing about this rule template is that it is very fast to execute. The reason is that one of the default claims that ADFSv2 retrieves is the list of all groups SIDs that a user belongs to. ADFSv2 does not need to do any additional account look up.
• This rule can only be used for users that authenticate locally using AD DS (Active Directory Domain Services) and come through ADFSv2 through the Active Directory Claims Provider Trust.

3. Transform an Incoming Claim

• This claim rule compares the type of an incoming claim to a selected type. Depending on its type, it can apply various actions to transform the type or value before issuing the outgoing claim to be returned to SharePoint.
• If the incoming claim matches the selected type, one option when configuring this rule is to simply pass it through and have it issued with the same type and value.
• Another option is to modify the type of the claim before it is issued as an outgoing claim. So, for example, an incoming claim could be of type “OrgStatus” and this rule could be used to issue it as the outgoing claim type “Status”, keeping its current value. Another incoming claim in the same environment could be of type “OrganizationStatus” and a similar rule could issue it as the outgoing claim type “Status”, again keeping its current value. This type of rule can help to normalize claim types when they are coming from various sources and perhaps have differing claim type names, but all mean the same thing.
• Additional options in this rule template allow you to modify the value of the claim before it is issued. The following options are available:
  • If the value of an incoming claim equals a specified value, then change its value to a new specified value before issuing the outgoing claim. There are no StartsWith, EndsWith or Contains-like options available here. More complex value checking requires a custom claim rule – see Part 2 of this blog series.
  • If an incoming claim contains an email suffix, then replace it with a specified email suffix.

4. Pass Through or Filter an Incoming Claim

• This claim rule compares the type of an incoming claim to a selected type. Depending on its type, it can optionally apply other filters before issuing the outgoing claim to be returned to SharePoint.
• If the incoming claim matches the selected type, one option when configuring this rule is to simply pass it through and have it issued.
• Another option is to filter it based on certain values. The following options are available for filtering:
  • Only issue the claim if its value equals a specified value – for example, if an incoming claim is of type ‘EmployeeStatus’ and if its value is ‘Full Time’. The claim is issued only if both conditions are met.
  • Only issue the claim if it is an email address and if it ends in a particular value – for example, check if the claim type is E-Mail Address, and if so issue it only if the email suffix is ‘titus.com’ or some partner email domain.
  • Only issue the claim if its value starts with a particular string – for example, check if the claim type is Department and if its value starts with certain department acronym.
• Claim values cannot be changed with this type of rule. They must either be issued or not based on their type and value.
• This rule can apply to claims that have been issued by previous rules. One interesting use for this type of rule is if certain claim types contain sensitive information and you do not want that information to be issued to certain relying parties. The issuing of certain outgoing claims can then be restricted based on their values.

Once a user has signed in and their claims are retrieved, SharePoint 2010 does a great job of enforcing permissions on documents and items to which claims have been assigned with a permission level. Of course a user must have those claims as part of their identity to gain access to a document or item with the assigned permission level. Centrally managing how claims are retrieve and returned through ADFSv2 claim rules can allow you to implement some very robust access control policies in SharePoint. Applying those claims with permission levels to documents and items in SharePoint is still a manual and labor intensive task that can be very error prone – for more information on how the TITUS SharePoint Security Suite can automatically assign such access control policies at a fine grained level in SharePoint please read the white paper Microsoft SharePoint Security – Harness the power of claims to protect information or check out the video.

Once again, for many security policies these rule templates are sufficient for achieving a policy’s intended purpose. If more sophisticated policies are required, ADFSv2 does provide a Claim Rule Language that can be used to author detailed policies with very specific conditions. Please see Part 2 of this blog series in order to learn more about how to use the Claim Rule Language.

-Antonio

SharePoint Security Paper: Harness the Power of Claims to Protect Information

The topic of claims, or trusted user attributes, is an established and well defined concept within the
identity management space. In SharePoint 2010, Microsoft introduced support for a claims-based identity model. Claims-based identities can be used in Microsoft SharePoint to enhance the process of user authentication. By harnessing the power of claims and extending its use to authorization, organizations can also effectively manage security and governance policies for accessing valuable information assets. It is important to
understand the many concepts of the claims-based identity paradigm in order to implement granular,
scalable and dynamic security within Microsoft SharePoint.

Organizations can implement and effectively leverage user claims in Microsoft SharePoint 2010 to securely share sensitive information. By implementing claims-based authorization in SharePoint and leveraging the benefits of trusted user attributes, organizations can solve many of the security challenges they face in their collaboration and file sharing environments. Further, it becomes evident that in order to properly manage security and fully realize the potential of claims, organizations must have solutions that automatically enforce access control and security policies on all of their SharePoint content.

This new white paper describes how organizations can implement and effectively leverage user claims in Microsoft SharePoint 2010 to securely share sensitive information.  Download the “Harness the Power of Claims to Protect Information” white paper, or go to our webpage, and learn how you can successfully implement claims-based authorization across all the SharePoint content in your organization.

Configuring the Realm – Using SharePoint 2010 with ADFSv2 to Retrieve Claims

When configuring SharePoint 2010 for claims based authentication or authorization you typically need to connect to an identity provider to retrieve user attributes as claims. To really see all the benefits of claims in the enterprise, we need to ensure that our SharePoint Server trusts the claims its receiving, and that often means configuring it to connect to a “trusted identity provider”. One such server application that can act as a trusted identity provider is Microsoft Active Directory Federation Services version 2.0 (ADFSv2). ADFSv2 is often also referred to as a ’secure token server’ because it plays the role of retrieving user attributes from Active Directory (or some other LDAP directory or data store), wrapping them up in a SAML token, digitally signing that token and returning it to the calling application – in this case SharePoint 2010. Configuring ADFSv2 in such scenarios can be tricky and unforgiving, and this article focuses on 1 particular part of that configuration – the Realm.

If you attended my session at the Microsoft SharePoint Conference a couple of weeks ago, called “Using Claims for Authorization in SharePoint 2010″, you would have seen my demonstration of SharePoint 2010 connecting to ADFSv2 to retrieve claims in a trusted manner, and then TITUS Metadata Security automatically applying authorization policies to documents in SharePoint based on a user’s claims and document metadata. During the demonstration, one person questioned the value I had configured for the “realm” variable. They very astutely noticed that it was configured to the following:

urn:sp-server-2010.sp.local:sharepoint2010

The portion of the realm which reads “sp-server-2010.sp.local” actually matches the domain of the SharePoint server I was using during my demo, and I think this implied the realm variable was doing more than it actually is, so I think this topic is worth a little clarification.

I’ll back up for a second to describe at a high level how I configured ADFSv2 and SharePoint, and then focus specifically on exactly how the realm variable is used.

High-Level Configuration of SharePoint 2010 and ADFSv2

When configuring SharePoint 2010 to authenticate through ADFSv2 and retrieve claims, the following is the process at a high level that you’ll typically follow in a very simple base case:

1. Download ADFSv2 from the Microsoft ADFS web site (its free) and after starting the setup program select to install it as a Federation Server.
2. On the ADFSv2 server, go into the IIS Management Console and create a self-signed certificate.
3. Within the ADFS 2.0 Management application, create a New Federation Service – there is a great wizard provided for this. Take note of the “Federation Service Name” (in my case it is https://sp-server-2010.sp.local) as its used a little later on.
4. Expand the Service node, and under the Claims Descriptions node add a new claims description for any custom claims you wish to return – there are 21 claims already there by default like Email. Here we are selecting claims to be sent back to SharePoint, but we are not yet mapping them to AD attributes. For any custom Claims Descriptions you’ve added, take note of claims type URL.
5. Expand the Trust Relationships node, and under the Relying Party Trusts node add a new relying party trust – there is a great wizard for this as well.  There are several options to choose here, but some of the critical ones are the following:
   - Select “WS-Federation Passive” as the protocol
   - For the Relying Party URL use the ‘Federation Service Name’ from above plus ‘/_trust/’ (so in my case its https://sp-server-2010.sp.local/_trust/)
   - For the Relying Party Trust Identifier here is where we need to specify a realm and where the confusion came in.  More on this point a little lower in this article.
6. Create Claims Rules for the Relying Party Trust you just configured. Here is where we map AD attributes to Claim Descriptions. For complex scenarios, consider using the Claims Rule Language built into ADFSv2.
7. View and Export ADFSv2 Token Signing Certificate – c:\adfs20Certificate.cer. You will need to copy this to the SharePoint 2010 server. We need to use this certificate when configuring SharePoint 2010.
8. In SharePoint you are now going to create a new web application. You’ll select that it uses Claims Based Authentication over NTLM to start, ensuring that it uses port 443 and SSL. Ensure the public URL of the web app matches the one in the ADFSv2 certificate – this is where we start to establish trust between this web app and the ADFSv2 server. Do not create a site collection yet.
9. You will then run a PowerShell script on the SharePoint server in order to map the claims being retrieved, set the realm and set the certificate that SharePoint should use to validate the claims received (the c:\adfs20Certificate.cer file described above). The PowerShell script is included below.
10. Finally, in SharePoint 2010 you will now log into Central Admin, access the Authentication Providers page for the web application you just created, click Default and check on “Trusted Identity Providers” and the ADFSv2 Provider you just configured. You can optionally uncheck the NTLM provider you configured earlier. You can now create a new site collection, site and libraries.

Now, there are a lot of details in each step and as mentioned the process can be unforgiving if mistakes are made. For a detailed end to end description of the entire process I encourage you to visit Steve Peschka’s Share-n-dipity blog.

The Realm

Now, getting back to the discussion on the realm – when creating a Relying Party Trust within ADFSv2, you are establishing a trust relationship between ADFSv2 and a calling application. In our case the calling application is SharePoint. When creating this trust, you need to specify a Relying Party Trust Identifier which is a realm. The realm can in fact be anything you want, as long as it follows the specific format:

urn:something:something_else

In my case, because the calling application was my SharePoint 2010 server I chose to use the URL associated with that server so it ended up looking like this:

urn:sp-server-2010.sp.local:sharepoint2010

…but I could have used anything I wanted after the “urn:” and after the second “:”. I would recommend avoiding spaces here though.

The realm is associated with the claims aware web application that’s making a request to ADFSv2 (again, in our case the SharePoint web application). When ADFSv2 receives a login request from SharePoint, it is uses the realm to map the request to one of the relying party trusts that has been configured. With that relying party trust, once the user has been authenticated, ADFSv2 then knows which attributes to retrieve, how to map or manipulate them and what protocol to use in returning them to SharePoint.

So, in our case, when I navigate to SharePoint at https:\\sp-server-2010.sp.local I’ll be redirected to ADFSv2 and it will receive the realm “urn:sp-server-2010.sp.local:sharepoint2010″ with the login request. Once I’ve been authenticated and ADFSv2 has retrieved, mapped, wrapped and signed my claims, ADFSv2 will redirect me to https:\\sp-server-2010.sp.local\_trust\ because that’s the WS Federation passive protocol URL that I configured with the relying party trust. Its important to note that the realm is simply used to map the calling app that’s making the login request to a configured relying party trust so that ADFSv2 knows how to deal with the request. The realm is not used at all to to redirect the user to any URL.

This realm value is also used in the step mentioned above which requires running a PowerShell script on the SharePoint server. That step configures the SharePoint web application with the realm to use in making its login request to ADFSv2 – so its important to use the same value configured in your relying party trust. Here is a sample of that PowerShell:


# Make sure the claim types are properly defined in the ADFS server
$map = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
$map2 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming
$map3 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.sp.local/EmployeeStatus" -IncomingClaimTypeDisplayName "EmployeeStatus" -SameAsIncoming
 
# The realm will identify the web app in ADFS. It is generally created in the form "urn:something:something_else"
$realm = "urn:sp-server-2010.sp.local:sharepoint2010"
 
# Use the certificate that has been exported from the ADFS server
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\adfs20Certificate.cer")
 
# The url below will tell SharePoint where to redirect to in order to authenticate with the STS
# so this should have the ADFS url, plus the protocol (Windows integrated security - "/adfs/ls")
$signinurl = "https://adfs20.sp.local/adfs/ls"
 
# Adds the STS (AD FS 2.0) to SharePoint
$ap = New-SPTrustedIdentityTokenIssuer -Name "ADFS20 Provider" -Description "SharePoint secured by ADFS20" -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map,$map2,$map3 -SignInUrl $signinurl -IdentifierClaim $map.InputClaimType
 
# The certificate imported from the ADFS should be added to the trusted store
New-SPTrustedRootAuthority -Name "ADFS Token Signing Root Authority" -Certificate $cert


Again, the script must be run on the SharePoint 2010 server. There is a lot going on in it including:

- mapping claim types
- configuring the realm which SharePoint will use in the login request
- specifying the certificate to use in validating the token received from ADFSv2
- adding the trusted identity provider to SharePoint – named “ADFS20″ Provider here
- adding the certificate from ADFSv2 to the trusted certificate store

I’ll mention one more time that its very important to ensure that you’ve included the correct realm and all the correct URLs in your PowerShell script. If you run it with typos it can often mean starting the whole process over again. Hopefully this helps to clarify any questions about how the realm is used in configuring SharePoint with ADFSv2.

More importantly, hopefully this post helps to clarify how trust is established between SharePoint 2010 and a trusted identity provider like Microsoft Active Directory Federation Services 2.0, because only when user attributes in SharePoint are trusted is the enterprise really going to fully benefit from Claims through Claims Based Authentication and Authorization.

-Antonio

Microsoft SharePoint Conference Presentation on Claims

I got quite a few questions and request for copies of my slides for the presentation I did a few weeks ago at the Microsoft SharePoint Conference 2011 in Los Angeles.   The presentation was called Using Claims for Authorization in SharePoint 2010. For an explanation of how claims can be used for authorization (deciding what documents or items users are allowed to see) in SharePoint click on this link to download my presentation. The PowerPoint has been converted to PDF format.

I have also started a blog series on Claims in SharePoint and here is my first post What are Claims – Using Claims in SharePoint.

Antonio