In previous three posts we examined how claim authentication flow works for users in the same domain as SharePoint site and for users from other organizations. As we have seen, the value for Role claim was based on the Active Directory group membership. For instance, Frank Miller from Fabrikam was given role of DrugTrial1Auditors in Contoso SharePoint site because he was member of DrugTrial1Auditors AD group in Fabrikom.com domain. With current configuration Contoso has no say which users from Fabrikam have DrugTrial1Auditors role on Contoso SharePoint site. Contoso trusts Fabrikam administrators to ensure that only authorized employees for DrugfTrial1Auditors belong to the Fabrikam DrugTrial1Auditors group. This can be perfect in some situations, but sometimes it might be not the best solution. What if Contoso wants to control what type of access users from Fabrikam should have to the Contoso SharePoint site, but at the same time they do not want to manage or create accounts for Fabrikam users? There is a great solution for it and step 8 in the demonstration shows a sample on how we can use SQL server database as source for external attributes for claim values. Figure 1 shows example tables for this solution.
Figure 1. External data source for user information
Table dbo.TS contains information about which SharePoint site belongs to which drug trial.
Table dbo.URT contains a list of e-mail addresses of users, the role that they have, and the drug trial that they belong to.
Table dbo.RS maps the roles in the database to the roles in the Contoso SharePoint site.
To accommodate data in these tables we had to modify SharePoint site. It was reconfigured with new roles: Role#sp_admin and Role#sp_visitor. DrugTrial1Auditor role and DrugTrial1Admin role were removed from the portal. Also, new datasource was added: “HOL Doctors Role” database.
Three new rules were created on the Contoso SharePoint RP. Each rule is using one of the database tables. Check out this site for ADFS v2 rule language format:
http://technet.microsoft.com/en-us/library/dd807118(WS.10).aspx
The first rule check which trial the https://docs.contoso.com/ site belongs to:
=> add(store = "HOL Doctors Role", types = ("http://schemas.microsoft.com/ws/2008/06/identity/claims/trial"), query = "select trial from dbo.TS where dbo.TS.SharePointSite = {0}", param = "https://docs.contoso.com/");
In second rule, we use the previously queried trial information with the user’s e-mail address and discover which role the user belongs to:
c1:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] && c2:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/trial"] => add(store = "HOL Doctors Role", types = ("http://schemas.microsoft.com/ws/2008/06/identity/claims/incomingtrialrole"), query = "select role from dbo.URT where dbo.URT.Trial = {1} and dbo.URT.UserName={0}", param = c1.Value, param = c2.Value);
In the third rule, we use a previously queried role claim to query the SharePoint role claim and assign the value to the outgoing role claim:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/incomingtrialrole"] => issue(store = "HOL Doctors Role", types = ("http://schemas.microsoft.com/ws/2008/06/identity/claims/role"), query = "select dbo.RS.SharePointGroup from dbo.RS where dbo.RS.Role = {0}", param = c.Value);
Lets take a look at how claim flow will work in this new configuration. Figure 2 shows slightly modified flow of authentication to Contoso SharePoint site from Fabrikam user.
Figure 2. Authentication by Fabrikam user to Contoso SharePoint site
Fabrikam user Frank Miller will access Contoso SharePoint site.
In step 1, Frank opens his browser and opens https://docs.contoso.com site. SharePoint site will provide its policy information a redirect Franks browser to a trusted STS.
In step 2, Franks browser will access https://sts1.contoso.com and reads its policy. At this point Frank must select his home realm. If Information Card was already configured in Fabrikam forest for Contoso SharePoint site, the home realm discovery would automatically redirect his browser to his home STS. Without Information Card, he would be required to choose his STS server in the drop down list. At this point no claims yet have been exchanged and all authentication been done via anonymous authentication mechanism.
In step 3, Franks computer will authenticate to the STS. Since our STS is running on the same computer as Domain Controller, it is already authenticated to it, so it just presents existing Kerberos ticket, which will have all required information in it, such as list of groups this user belongs to (list of SIDs of those groups).
In step 4, Fabrikam STS will create and process new claim for Frank Miller. The first rule will create the following claim:
Next, it will pass this claim onto second and 3rd rules. Second rule allows to pass all claims with any E-Mail Address. 3rd rule will check value of the Role claim type and it will discard 2 values out of this claim. The final outgoing claim from Fabrikam STS for user Frank Miller should have the following information:
In step 5 this claim is delivered back to Franks computer.
So now Frank has his claim from Fabrikam STS. Can he present this claim to Contoso SharePoint site? It would not work because Contoso SharePoint site does not trust Fabrikam STS, it only trusts Contoso STS and it would accept claims only from Contoso STS.
In step 6, Franks computer will deliver his claim to Contoso STS.
Now it is up to Contoso STS to evaluate incoming claim and decide what to do with it. In steps 7, 8 and 9 Contoso STS receives incoming claim from Fabrikam STS and it will pass it onto Fabrikam IDP rule set configured on Contoso STS. If you remember, those rules will evaluate incoming claim values and will pass claims only if their E-Mail Address value ends with @fabrikam.com and its role value is equal to DrugTrial1Users. Incoming claim from Frank satisfies both criteria. At this point Contoso STS accepted incoming claim, it is not going back out yet to the user computer. The value of this claim should be the same as it came in:
Next, it will pass this claim onto Relying party rule set to create outgoing claim suitable for the SharePoint. Now Contoso SharePoint RP is configured with five rules for incoming claims. First one will pass Role claim type without any changes to its Role type. Second rule is a transformation rule. It will change the E-mail Address claim type to Name claim type, but will keep its value the same. The 3rd rule will identify that DrugTrial1 trial belongs to https://docs.contoso.com site. The forth rule will identify that Frank has Admin role in DrugTrial1 trial. And finally, the fifth rule will identify that Admin for DrugTrial1 mapped to sp_admin role in SharePoint site.
The final claim for Frank Miller, coming out from Contoso STS destined for SharePoint RP should look like this:
OK, to recoup, lets compare claim originated at Fabriakm STS and final claim delivered to Contoso SharePoint:
.
This is continuation of two previous posts. Please check them out first, otherwise this one might not make much sense at all.
Step 6 in step-step guide configures Fabrikam STS with Relying Party and shows how to configure Information Cards to automate home realm discovery. I’m not going to talk about Information Cards yet, for now we stick with STS configuration and claims flow.
Afetr the RP for Contoso STS was created we configured three claim rules. The first rule is using AD as the directory source. It should be easy to predict the mappings in this rule. Just take a look back at how Fabrikam IDP on Contoso STS was configured. It expects certain type of incoming claims. This rule has the following mappings:
This could be configured to just send this claim out to the relying party, but it was not. Fabrikam STS Administrator decided to provide some extra checks and only send out claims that match certain criteria.
The following table shows two new rules:
The first rule will pass any E-Mail Address claim, but the second rule will filter out all claims that do not have DrugTrial1Auditors in its value.
At this point users from Fabrikam are ready to access Contoso SharePoint site.
What is the single qualifying requirement for Fabrikam user to get access to the Contoso site? Fabrikam user must be member of DrugTrial1Auditors Active Directory group.
Lets examine the entire authentication flow for Fabrikam user. Figure 1 provides steps in this process.
Figure 1. Authentication by Fabrikam user to Contoso SharePoint site
Now it is up to Contoso STS to evaluate incoming claim and decide what to do with it. In step 7, Contoso STS receives incoming claim from Fabrikam STS and it will pass it onto Fabrikam IDP rule set configured on Contoso STS. If you remember, those rules will evaluate incoming claim values and will pass claims only if their E-Mail Address value ends with @fabrikam.com and its role value is equal to DrugTrial1Users. Incoming claim from Frank satisfies both criteria. At this point Contoso STS accepted incoming claim, it is not going back out yet to the user computer. The value of this claim should be the same:
Next, it will pass this claim onto Relying party rule set to create outgoing claim suitable for the SharePoint. Contoso SharePoint RP is configured with two rules for incoming claims. First one will pass Role claim type without any changes to its Role type. Second rule is a transformation rule. It will change the E-mail Address claim type to Name claim type, but will keep its value the same.
In step 8, this claim is send back to Franks computer, in step 9 it is delivered to Contoso SharePoint site. SharePoint site will authenticate Frank Miller (frankm@fabrikam.com) at gives him appropriate rights configured for Role#DrugTrial1Auditors. Just like that simple and easy.
In next post we’ll look at how role membership information can be outsourced to SQL database.
In previous post we started examination of the authentication process in our demo environment. Lets examine what happens in step 5 of the step-step guide. During this step Contoso STS was configured to work with Fabrikam STS. There were three primary steps in this process:
Fabrikam IDP is configured with two rules:
So what does it mean? We are saying that Contoso STS will accept two types of claims from Fabrikam STS:
Also, it will evaluate the value of incoming claim and will pass only claims with specific identified values. One thing we have to keep in mind here is that some time in the design process folks from Contoso and Fabrikam have actually discussed the type of claims will be exchanged between each STS. Because if Fabrikam STS is configured to send different types of claims to Contoso, nothing will work. Also, IDP rules are not sending incoming claims to actual RP or the user browser, they are received, evaluated and if they pass the filter, they are passed through onto the configured STS RP.
So next, RP rules must be modified to evaluate incoming claims and perform some action on them. Contoso SharePoint RP already has one rule set configured on it. Two new rules must be configured, one for each incoming claim type from Fabrikam IDP.
Contoso SharePoint RP is configured with two additional rules:
The first rule will pass through any “role” claim type, it doesn’t care about its value.
The second rule will take the value of the “E-Mail Address” claim and pass this value but in a different claim type – in this case as claim type of “Name”. This is powerful stuff. Contoso SharePoint needs to identify a user by its name and it does so via claim type of “Name”. Fabrikam on the other hand does not send this type of claim from its STS. If we could not do claim transformation then this solution would not work or both parties would have to agree on every single claim and its syntax, and every application would be required to comply with those requirements. Claim transformation eliminates this limitation and gives us a lot of flexibility.
Lets examine how one specific claim would go through Fabrikam IDP and then through Contoso SharePoint RP. In this example Fabrikam STS send the following Claim to Contoso STS:
Fabrikam IDP rules will examine this claim and since both conditions are met it will pass through it.
Next, the Contoso SharePoint RP will evaluate this claim. After it goes through its rules the resulting claim should have the following information:
This data will be send to the end user and then presented to the SharePoint site for authentication.
Key Learning's
In the next post we’ll examine how Fabrikam STS will construct outgoing claims and look at the whole flow of this process.
Claims based authentication is getting more ground and with more practical applications we’ll see more and more adoption of this technology. Recently I downloaded and went through step-step demonstration on using Microsoft Office SharePoint Server 2007 and Active Directory Federation Services v2 (ADFS v2) beta 2 software. You can download this great demo at this location (http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=57602615-e1ee-4775-8b79-367b7007e178).
I have done simple implementations with ADFS v1 in the past and have read a good amount on ADFS v2 and in general on Claims based authentication, so I’m not new to this concept and technology in general. It doesn’t take long to go through all of the steps in this demonstration and it actually fairly easy and everything works. After going through all of the specified steps I scratched my head and thought, hmm, how is it exactly working, what is happening there, what kind of claims are going between IDP and RP, how are they configured and how can I modify this configuration to do other things? I like to visualize things, if it at all possible. This way I can see it, visually touch it and can get much better long term understanding on how this solution is actually working. So I decided to walk through this configuration and try to document some of those parts needed for better understanding of the entire message workflow.
If you are new to Claims based authentication, this post might not make much sense to you. There are a lot of resources on this subject. At the the of this post I provide some links to blogs and white papers that I think are very informational and educational.
First, I want to review the design of this demonstration. Figure 1 shows both Fabrikam and Contoso environments.
Figure 1. Base configuration of Fabrikam and Contoso
If you didn’t have a chance to review step-step document then here is a quick review of this solution. Contoso is doing business with Fabrikam and as part of their business environment they need to provide a secure collaboration portal. Contoso is using SharePoint 2007 to share documents between Contoso and Fabrikam. Contoso does not want to manage Fabrikams user accounts and Fabrikams does not want to have more than one user account and would like to have single sign on to access resources on Contoso SharePoint portal. Access to resources must be controlled via assigned roles. Some users should have only read access, some contributor access and some full access to the content.
As you can see, each company has its own Active Directory environment. They do not have Active Directory Forest or domain trusts and users in one environment can’t authenticate to other environment via AD trusts. Contoso AD does not have duplicate accounts for Fabrikam users.
Fabrikam users will access resources in Contoso SharePoint portal via Claims based authentication and they will have certain rights (roles) based on the assigned group membership in their own Fabrikam AD environment.
In step-step guide, in step 4 you’ll be asked to authenticate as Contoso\Administrator to the https://docs.contoso.com and add new roles to the site. In prior steps you configured this site to use “Role#Domain Admins” as site administrator and configured ContosoSRV01 ADFS with RP for SharePoint site with couple claim rules.
So what happens during this authentication and what type of claim is actually provided to the SharePoint site to give Contoso\Administrator administrative rights on the site? Figure 2 shows authentication steps.
Figure 2. Authentication by Contoso user
In step 1, Administrator accesses https://docs.contoso.com site, his browser reads the policy on the SharePoint site, discovers that it need to get a Claim from sts1.contoso.com and get redirected to it.
In step 2, he chooses to use Windows Integrated Authentication to authenticate to STS.
In step 3, he will get required claim from STS. STS is configured with the following rules:
Based on these rules, the content of this claim will be the following:
In step 4 this claim is send back to the https://docs.contoso.com SharePoint site.
Sharepoint site will take the claim, evaluate it and will find that one of the values in Claim Type Role is “Domain Admins” which matches its own configured Role type (“Role#Domain Admins”). Based on this match SharePoint will give our Administrator administrative rights to this site.
OK, this is fairly easy stuff. One to one matching and we are in business. As we can see Administrator Role Claim value has multiple groups in it. Obvious question begs the answer, can we configure SharePoint roles provider with any of these groups to give this user administrative access on the SharePoint? and the answer is yes. To prove this we can do a quick test. We’ll modify SharePoint to use “Role#Schema Admins” instead of “Role#Domain Admins”. Since Administrator account is member of Schema Admins group, he will have administrative rights on the site.
During step 4 (step-step guide) Administrator configures site with couple new roles: “Role#DrugTrial1Admins” and “Role#DrugTrial1Auditors”. At the end of step 4 we’ll authenticate as user Contoso\Danielw and verify that he has appropriate rights. Same flow will happen as shown in Figure 2. Based on the configured rules the claim will have the following values:
Because Daniels claim type ‘Role” has value matching SharePoint configured role, he is will be given appropriate rights on this site.
Key Learning's:
Additional Research Items
In the next post we’ll continue examination of this configuration.