Below is the link to the AD Secure Store Code and Scripts

The first part to make the Temp Share application is to enable a custom ribbon control.  You will see on the image below that we have a Temporary Share ribbon icon.  This button is used for single or bulk sharing of documents.  Custom ribbon controls are done through defining a CustomAction and the Javascript for loading the dialog box.

The custom action for the TempSharingButton sets up the notification and dialog framework for when the button is clicked.  When the dialog box launch it reverts back to the Site collection root as the current site.  In our case we are interested in interacting with documents in the currently site and list set.  To keep the context of the current site we need to pass the {SiteUrl} as part of the dialog options.  We also pass a list of the Document IDs to the dialog box which loads the UserShareDialog.aspx control.

The ribbon control loads the External File Sharing dialog up with the selected documents from the list.  The External File Sharing form allows a temp sharing sponsor to specify any external user access by leveraging their partner Email, Facebook account, Gmail account, LiveID, Yahoo, etc.  We enable this trusted authentication through public federation leveraging Azure ACS which we will talk about later in the article.  The sponsor also specifies the amount of time the documents should be shared for.  From this form input a security token is generated using an SHA1 hash.  The token is logged to a SQL database storing temporary shared files and the token is also put on the SharePoint document.

The SharePoint item permissions are changed and the TempShareToken is added, notice below we have the SHA1 hash we generated with a read permission set on the item.  The token is set as a custom claim which our custom claim provider tempshareclaimsprovider will be responsible for filling when I log in with my Facebook account Nathan.Miller@microsoft.com.

Below is code for applying the Temp Share token to the documents. Adding the security token to the document will allow the external user to download or view the shared document.  To add a claim to the document we need to get the provider manager and encode the claim.  When we add the claim to the document it will also add the claim also to the web site with a limited access.  Notice we are breaking item inheritance when we add the token, so this approach should be considered only for specific site collections.

using (SPWeb web = elevSite.OpenWeb(webUrl))
 {
 SPClaimProviderManager claimMgr = SPClaimProviderManager.Local;
 if (claimMgr != null)
 {
 SPFile file = web.GetFile(docId);
 SPClaim spTokenClaim = Util.GetSharingTokenClaim(sharingToken);
 string claimUserName = claimMgr.EncodeClaim(spTokenClaim);
 // Need to Escalate Privs.
 SPUserInfo userInfo = new SPUserInfo
 {
 LoginName = claimUserName,
 Name = "TempShareToken"
 };
 
 if (file != null)
 {
 web.AllowUnsafeUpdates = true;
 // Add the Claim to the Web.
 SPRoleAssignment roleAssignment = new SPRoleAssignment(userInfo.LoginName, userInfo.Email, userInfo.Name, userInfo.Notes);
 
 // Can't Add Read to the Item.
 SPRoleDefinition roleDefinition = web.RoleDefinitions.GetByType(SPRoleType.Reader);
 roleAssignment.RoleDefinitionBindings.Add(roleDefinition); 
 
 // Add the Claim to the Item.
 SPListItem item = file.Item; 
 
 if (!item.HasUniqueRoleAssignments)
 item.BreakRoleInheritance(true);
 
 item.RoleAssignments.Add(roleAssignment);
 item.Update();
 
 web.AllowUnsafeUpdates = false;
 }
 }

We also want to improve the user experience for sharing content over leveraging just SharePoint permissions.  To do this we added a Sponsors file for the Temp Share file sponsor to manage the files and who he is sharing with.  In this case Brad has two files shared with Nathan.Miller@microsoft.com

The Sponsors files are retrieved by calling a Stored Procedure and loading the results property to a web part.  The Unshare link you see on the web part executes an Expire Flag of the document immediately.

using (SqlCommand cmd = new SqlCommand("dbo.spGet_SharedDocumentsBySponsor")) {
 
 … Code removed for setting up cmd parameters
 
 using (SqlDataReader reader = cmd.ExecuteReader())
 {
 if (reader.HasRows)
 {
 while (reader.Read())
 {
 SharedFile sharedFile = new SharedFile();
 sharedFile.DocumentId = reader.GetString(0);
 sharedFile.Sponsor = sponsorId;
 sharedFile.userShare = reader.GetString(2);
 sharedFile.claim = GetSharingTokenClaim(reader.GetString(4));
 sharedFile.expDate = reader.GetDateTime(5).ToString(); 
 sharedFile.WebUrl = reader.GetString(6); 
 sharedFiles.Add(sharedFile);
 }
 }

Custom Security Provider

We have logged the Shared documents to the database with the Hash code, time expiration and the person we are sharing the file with.  We also changed the security on the item to allow the user we are sharing the item with a user with the email identity of Nathan.Miller@microsoft.com.  Now we need to get the document security tokens loaded as User claims for when the external user logs in.  This is done by using a Custom Security Provider.

Security Providers are farm level features, as a best practice we want to only activate this security provider for a particular web application so in order to enable a claims security provider for only one web app we need to set the provider attribute to not be used by default and then add a Web App Feature which will activate the Security Provider only for the web application where we enable the feature.  To do this we implement a SPFeatureReciever that is scoped at the Web Application level.  In our Web Application feature we are setting up two patterns:

1. A Web App Policy to deny Write to our Temporary Shared Users.  This protects us from any miss configuration.
2. We call the toggle TempSharingProvider to enable the provider for our Web Application in the Claims Provider Collection.

 public class TempSharingConfigureWebAppFeatureEventReceiver : SPFeatureReceiver {
 // Uncomment the method below to handle the event raised after a feature has been activated.
 
 public override void FeatureActivated(SPFeatureReceiverProperties properties)
 {
 if (properties != null)
 {
 if (properties.Feature.Parent is SPWebApplication)
 {
 SPWebApplication webApp = properties.Feature.Parent as SPWebApplication;
 SPIisSettings settings = webApp.GetIisSettingsWithFallback(SPUrlZone.Internet);
 settings.ClaimsProviders = toggleTempSharingProvider(settings, true);
 
 SPIisSettings defaultZoneSettings = webApp.GetIisSettingsWithFallback(SPUrlZone.Default);
 defaultZoneSettings.ClaimsProviders = toggleTempSharingProvider(defaultZoneSettings, true); 
 
 // Adding the Deny Write to the Web Policy.
 SPPolicyCollection zonePolicies = webApp.ZonePolicies(SPUrlZone.Internet); 
 SPPolicy tokenSharingPolicy = zonePolicies.Add(Util.TokenSharingEnabledClaim.ToEncodedString(), RuntimeConstants.WEBB_APP_POLICY_NAME);
 SPPolicyRole readOnlyPolicy = webApp.PolicyRoles.GetSpecialRole(SPPolicyRoleType.DenyWrite);
 tokenSharingPolicy.PolicyRoleBindings.Add(readOnlyPolicy);
 
 webApp.Update(true);
  }
 }
 }
 
 static List<string> toggleTempSharingProvider(SPIisSettings webAppSettings, bool enable)
 {
 List<string> providers = new List<string>();
 
 foreach (string s in webAppSettings.ClaimsProviders)
 {
 // If the Feature is redeployed and not activated the Provider will get added twice.
 // This is preventing duplicate providers.
 if (!providers.Exists(p => p == s))
 providers.Add(s);
 }
 
 if (enable)
 {
 if (!providers.Exists(p => p == RuntimeConstants.ProviderInternalName))
 providers.Add(RuntimeConstants.ProviderInternalName);
 }
 else
 {
 if (providers.Exists(p => p == RuntimeConstants.ProviderInternalName))
 providers.Remove(RuntimeConstants.ProviderInternalName);
 }
 
 return providers;
 }

User authentication and sharing with our External users is done in our scenario through leveraging public federation and we use Azure ACS in this scenario, so we just need to worry about augmenting the identity claims with our shared tokens when the user logins in.
Our Claims provider is actually fairly simple.  We fill two types of claims.  First, a provider status claim to let us know whether or not to enable the Temp Sharing Ribbon button and the second claim we fill the Sharing Token Claim Type as the key to accessing the individual items. 

 protected override void FillClaimTypes(List<string> claimTypes)
 {
 if (claimTypes == null)
 {
 throw new TempSharingClaimsProviderException(RuntimeConstants.Strings.exp_invalidOrNullClaimTypes);
 }
 claimTypes.Add(RuntimeConstants.SharingTokenProviderStatus);
 claimTypes.Add(RuntimeConstants.SharingTokenClaimType);
 }
 

To fill the sharing token claims for the external user we implement the FillClaimsForEntity in our claim provider.  In this method we call GetSharingTokens for the current user.  This queries our database to retrieve all of the document paths shared for the user and the security Hash token for each document.  We then add the SharingTokenClaimType for each token to the current users claims.

 protected override void FillClaimsForEntity(Uri context, SPClaim entity, List<SPClaim> claims)
 {
 if (claims == null) throw new ArgumentNullException(RuntimeConstants.Strings.exp_invalidOrNullClaimTypes);
 
 //This claim provider is enabled so issue a claim that allows the temp sharing.
 //This will let the user into the web app
 claims.Add(Util.TokenSharingEnabledClaim);
 
 SPClaimProviderManager cpm = SPClaimProviderManager.Local;
 
 //get the current user so we can get to the "real" original issuer
 string userIdForTokenSharing = Util.GetCurrentUserId(entity);
 
 List<SPClaim> documentTokens = Util.GetSharingTokens(userIdForTokenSharing);
 foreach (SPClaim tokenClaim in documentTokens)
 {
 //Issue the sharing token as claims
 claims.Add(tokenClaim);
 }
 }

Our utility method for loading a users SharePoint claims (Util.GetSharingTokens()) with all of the tokens from the documents that are shared with them.

 public static List<SPClaim> GetSharingTokens(string userId)
 {
 List<SPClaim> tokens = new List<SPClaim>();
 SPSecurity.RunWithElevatedPrivileges(() =>
 {
 using (SqlConnection conn = new SqlConnection(ConnectionString))
 {
  using (SqlCommand cmd = new SqlCommand("dbo.spGet_TokensForUser"))
 {
  … Removed Parameter code for passing the User ID 
 using (SqlDataReader reader = cmd.ExecuteReader())
 {
 if (reader.HasRows)
 {
  while (reader.Read())
 { 
 tokens.Add(GetSharingTokenClaim(reader.GetString(2))); //Issue the token
 }
 

The external user is now able to log into the system.  As we said before we are using Azure ACS as our Trusted Authentication to SharePoint which will redirects us to the Facebook login in this scenario.

Once we authenticate we are passed to the SharePoint site with our External Users email address as their user ID.

Our internal user shared two documents with nathan.miller@microsoft.com.  We are now able to view these document and download them from our external zone.  Notice we created a web part for our external users to retrieve any of their shared documents.  This works the same way as the Sponsors web part querying the database and showing the documents that are shared through a custom .Net control.

If we take a look at the claims that were filled by our Trusted Login provider (Azure) we see the emailaddress is set as the users identity.  We also see the Facebook AccessToken mapped (though we didn't have to), gmail, yahoo and a partner ADFS are also configured in this demo.  Finally, you can see the claims that we loaded with the provider the tempsharingtoken claim types are the SHA1 hash tokens that we put on the documents.  If the user has the claim token and we have the claim type added to the document with a permission of read, this gives the user access to the documents.

TempShare2.0.zip

The video below will help illustrate the end user experience with this blog entry focused on how the implementation and architecture is implemented for this type of capability. 

An overview of the solution shows that there are 3 main components.

1. The ProfileClaimsManager is the application page used for saving configuration settings.
2. The Profile Claim provider is a custom claim provider responsible for loading the users claims and the people picker search logic.
3. The ProfileClaimsModel.edmx is the entity model used for interacting with the profile database views and the configured claims database.

The Profile Claims Manager Page

We use our custom Application page called the Profile Claims Manager to allow administrators to configure profile properties to be used for securing content.  This form will save the configured attribute claims.  Configured claims impact the People Picker in the web application, it also impacts the users during login as it fills the specific user claims based on the users profile values.

The claims configure above have the following impact to the portal.  The configured claims in this case Company, Department and EmployeeType will show up in the People Picker.   See below the rendered People Picker after the claims have been configured through the Profile Claims Manager.

Searching on "Strategy" in the people picker will filter and show departments that contain the term Strategy like the "CRM Strategy" and "Strategy Consulting".  How we resolve these search terms is part of our custom claim provider, in this case we decided to only check for a contains in the keyword search.  Selecting Strategy Consulting will then allow anyone with a Department = Strategy Consulting to access the SharePoint content we secure.

When a user logs in such as CONTOSO\Brads in this case.  You will see when we list the claims that get filled during Brads login it shows the windows identities, windows security groups represented by the groupsid ids toward the bottom these are filled in the normal windows/SharePoint claims process.  In the middle of the claims list you will see there is a https://schemas.contoso.com/Profile/* these are the claims that were configured through the Profile Claims Manager screen and their values. 

For Brad's case these claims are:

• Department = "Strategy Consulting"
• Company = "Contoso"
• EmployeeType = "Employee"

It's important to note that we are just augmenting the security, normal Kerbros / NTML with AD groups all still works we just add an additional security layer on top for our attributes.

Note:  The Claim Viewer Web Part is just a helper part that is used to dump configured claims.   Here is the code from the claims Viewer. 

 public class ClaimsViewer : WebPart
 {
 protected override void CreateChildControls()
 {
 IClaimsPrincipal claimsPrincipal = Page.User as IClaimsPrincipal;
 IClaimsIdentity claimsIdentity =(IClaimsIdentity)claimsPrincipal.Identity;
 
 GridView gridView = new GridView();
 gridView.ID = "claimsGrid";
 gridView.DataSource = claimsIdentity.Claims;
 gridView.DataBind();
 Controls.Add(gridView);
 }
 }

The Profile Claim Provider

 The Profile Claim provider augments the users claims with profile attribute claims.  There are a couple major parts for the Profile Claims Provider.  First, most claim providers register the claims types they fill and usually use a static variable with the claim fill type and the claim value type.  In this case we are dynamically filling the claims based on the configuration, so we have to do it a little differently.  We need to read the database during the FillClaimTypes and FillClaimValueTypes to retrieve all of the configured claims and add them to the FillClaimTypes registration.

Note:  The ClaimsEntities is the database entity model that is used and documented later in this article.

public static string providerClaimType = "https://schemas.Contoso.com/Profile";
 
protected override void FillClaimTypes(List<string> claimTypes)
{
 if (claimTypes == null)
 throw new ArgumentNullException("claimTypes");

 SPSecurity.RunWithElevatedPrivileges(() =>
 {
 ClaimsEntities claimsDb = new ClaimsEntities();
 
 string claimKey = string.Empty;
 foreach (ClaimProperty claimProperty in claimsDb.ClaimProperties)
 {
 claimKey = String.Format("{0}/{1}", providerClaimType, claimProperty.ProperyName);
 claimTypes.Add(claimKey);
 }
 });
}
 

The Fill Claim For Entity is the main method executed during the User Login process.  Our code simply gets the User Profile Properties from our entity model and adds a new claim for the user based on each configured profile property.

protected override void FillClaimsForEntity(Uri context, SPClaim entity, List<SPClaim> claims)
{ 
 if (entity == null) throw new ArgumentNullException(providerInternalName + ":Invalid Entity");
 if (claims == null) throw new ArgumentNullException(providerInternalName + ":Invalid claims collection");
 
 string userId = entity.Value.Split('|')[1];
 Dictionary<String, String> userProfileProperties = ClaimsHelperClass.GetUserProfileProperties(userId);
 
 foreach (KeyValuePair<String,String> userProfileProperty in userProfileProperties)
 { 
 claims.Add(CreateClaim(string.Format("{0}/{1}",providerClaimType,userProfileProperty.Key),userProfileProperty.Value, claimValueTypeString));
 }
}

Fill Resolve needs to be implemented for the People Picker to resolve a searched or typed in claim.  FillResolve is also called during some system events. 

protected override void FillResolve(Uri context, string[] entityTypes, string resolveInput, List<PickerEntity> resolved)
{
 // Search a list of FB Groups to use for security. 
 if (!EntityTypesContain(entityTypes, SPClaimEntityTypes.FormsRole)) 
 return;

 // Call our Resolve Claim Value which search the current collection of claims to resolve.
 
 // If we find one add it to the picker.
 List<ProfilePropertyValue> resolveClaims = ClaimsHelperClass.ResolveClaimValue(resolveInput, true);
 
 if (resolveClaims.Count == 1)
 { 
 foreach (ProfilePropertyValue resolvedClaim in resolveClaims)
 resolved.Add(getPickerEntity(resolvedClaim));
 }
}
 

In our implementation the ClaimsHelperClass.ResolveClaimValue is called from each of the FillResolve and the Search.  This allows us to reuse the logic for a wild card search or an exact match search.  Below is the code from the ResolveClaimValue.  It simply queries the entity model and returns a list of claims that match the search criteria.

public static List<ProfilePropertyValue> ResolveClaimValue(string searchPattern, bool exactMatch)
{
 List<ProfilePropertyValue> claimMatches = new List<ProfilePropertyValue>();

 // If we need to get an exact match on a claim value (such as in FillResolve).
 ClaimsEntities claimsDb = new ClaimsEntities();
 SPSecurity.RunWithElevatedPrivileges(() =>
 { 
 // This can return multiple Properties for the provider, even if Value is an exact match. 
 // Need to do a secondary filter on Property.
 
 if (exactMatch) // If FillResolve on an Exact Match
 {
 var propertyMatches = claimsDb.GetProfileProperty(searchPattern);
 claimMatches = propertyMatches.ToList<ProfilePropertyValue>();

 } 
 else // If using PeoplePicker Search to Find Claims
 {
 var propertyMatches = claimsDb.SearchProfileProperties(searchPattern);
 claimMatches = propertyMatches.ToList<ProfilePropertyValue>();
 } 
});
 return claimMatches; 
}
 

The other key logic area for the Claim provider is the GetPickerEntity.  This method is responsible for returning the format, display and value of the people picker entity used in each of the Search and Fill Resolve.   We configured these claims with an Entity Type of FormsRole.  This treats the claim as a security group augmentation similar to how a Forms security provider would work.

private PickerEntity getPickerEntity(ProfilePropertyValue profileProperty)
{ 
 PickerEntity entity = CreatePickerEntity(); 
 string claimValue = ClaimValue(profileProperty);
 entity.Claim = CreateClaim(string.Format("{0}/{1}",providerClaimType,profileProperty.PropertyName), profileProperty.PropertyVal, claimValueTypeString);
 entity.Description = string.Format("Profile:{0}", claimValue);
 entity.DisplayText = string.Format("{0}", profileProperty.PropertyVal); 
 entity.EntityData[PeopleEditorEntityDataKeys.DisplayName] = claimValue;
 entity.EntityType = SPClaimEntityTypes.FormsRole;
 entity.EntityGroupName = profileProperty.PropertyName;
 entity.IsResolved = true;
 return entity;
}
 
private string ClaimValue(ProfilePropertyValue profileProperty)
{
 return string.Format("{0}={1}", profileProperty.PropertyName,profileProperty.PropertyVal);
} 

 The Profile Claims Entity Model

The solution uses an Entity Model (ProfileClaimsModel.edmx) for filling Claims from the Profiles database and configured profile properties. 

Note:  The Entity Model connection string is in the solution under App.Config, Application configuration settings need to be deployed to Central Administration, the STS Web Service and the Web App that requires use of the custom claim.

Database that stores Views for querying Profile database tables and save configured Claim Properties.

User Profile View pulls UserProfile_Full table from the Profile database (in this case [Profile DB] is the profile database.

The User Profile Properties view is used to pull the User, Profile Properties and their values back to fill the Claims.  Notice that a join to the ClaimsProperties table is in the query which will filter to pull back only configured claim values.

Note:  SharePoint Claims are an OR not an AND.  It isn't possible to add additional security of (Department = HR AND Position = Manager).  Though you could extend the profile provider to also issue Audience claims (leveraging Target Audiences) to handle some of the AND attribute scenarios.

ProfileClaims.zip