About Relying Party STSs (a.k.a, what is RequireFederatedIdentityProvisioning?)

A useful, yet sparsely documented feature of Windows CardSpace is its support for resource side Security Token Services (STSs) – STSs that are used by relying parties rather than Identity Providers. Vittorio has done an excellent job helping to provide detail on this subject, and I highly recommend people interested in understanding more about what resource STSs are and why they are useful, read his post. In this post I want to fill out some of the technical details. That said, I’ll start with a short introduction to the subject with an example I’ve found particularly helpful.

The canonical CardSpace scenario has a relying party (RP), usually a website, which requires a token from an identity provider (IP). The user selects a card in CardSpace. CardSpace then requests a token from the corresponding identity provider. A token is returned to the CardSpace client, which then sends it to the relying party. Figure 1 shows the RP site, and the IP STS the RP has a relationship with. In the following figures, the line connecting IPs and RPs indicates where explicit relationships exist.


Figure 1

Now, part of the flexibility of CardSpace and the Identity Metasystem, is that it is trivial for an RP to set up new relationships with multiple IPs, as shown in figure 2.


Figure 2

What’s interesting about the case with one RP and multiple IP’s is that the RP site maintains the logic about how to authenticate the various IPs, and potentially has logic to understand the different claims the IPs release (for example one IP could release the claims ‘first name’ and ‘last name’, and another ‘full name’. The RP needs to know how to normalize these into values it understands). Additionally, if the different IPs creates tokens in different formats, the RP needs to know how to understand each of these formats.

This is fine, and a good way for an RP to be able to work with multiple IPs. Now say the RP is part of an organization that needs publish more than one website or web services. Each site needs to duplicate the logic for understanding how to communicate with multiple IPs (show in figure 3)


Figure 3

Clearly for RPs with many sites and many partners, this can become unwieldy. It can be a lot of relationships that need to be maintained in multiple locations. A standard solution to this complexity is for the RP to also run an STS. The relying party’s STS maintains all of the logic around communication with the various IPs, and produces a consistent token format. The other RP sites can then request a token from the RP STS, and only need be able to process this token (figure 4).


Figure 4

RP STSs are not for everyone, but can be a big simplification for complex deployments.

STSs are just specialized web services, so expose policy about how to connect to them, including security requirements. The security requirements may state that issued token is required from another RP STS; this can create a chain of STSs. In the browser scenarios CardSpace automatically follows the RP STS chain, contacting the correct STSs, resolving their policy and continuing to the next STS. In the case of a Windows Communication Foundation (WCF) application, the policy chain can be resolved from a configuration file, but CardSpace itself doesn’t resolve the policy chain (the underlying difference here is a call to CardSpace’s GetBrowserToken() API or GetToken() APIs).


Figure 5

The policy chain can be longer than just a single RP STS, as shown in Figure 5. In this example, the RP Site would specify the requirements of the token it requires from RP STS 1; this would include required claims, STS endpoint URL, and STS metadata exchange policy (MEX) endpoint. Similarly, RP STS 1; would specify the requirements of the token it requires from RP STS 2. RP STS 2 would then specify the requirements for the token it needs. Since the token comes from an IP STS, the only required information is a least one required claim; the details about how to the IP STS can be retrieved from the card the user selects. However, RP STS 2 may also specify an issuer, so only cards from the desired issuer are user selectable.

Of course, the more STSs in the chain, the more processing time is required to request all of the tokens. This delay will be noticed as CardSpace starts (chasing the policy chain) and when it closes (retrieving the tokens). During these delays, the user sees the CardSpace progress page (figure 6).


Figure 6

To get CardSpace to follow an STS chain, it needs to be given the STS endpoint and MEX policy endpoint of the RP STS, as well as the claims that are being requested from the RP STS. This can be done from a web site by using the x-informationCard object tag. The issuer param is used to specify the STS endpoint, issuerPolicy specifies the MEX policy endpoint.


CardSpace will retrieve the policy from the issuerPolicy URL. Since a MEX policy can define policy for multiple STSs, the issuer URL must match one. The policy for the RP STS is then used to decide what to do next. If it is an IssuedToken request that can be satisfied by a self issued or managed card, CardSpace shows the user her cards, and the usual user interaction begins. One interesting point to note; the policy from the RP STS, not the RP site, is used for card selection. This makes sense, because the token returned by the IP STS must satisfy the RP STS requirements and the token from the RP STS satisfies the requirements of the RP website.

The steps in a CardSpace interaction with an RP website, RP STS and IP STS, are listed below, and shown in figure 7.

1) The user goes to the RP website

2) Token requirements are returned via the x-informationCard object tag

3) CardSpace queries for policy from the RP STS

4) Policy is returned from the RP STS

5) The user selects a card that matches the RP STS policy

6) CardSpace makes a request for a token from the IP STS (RST)

7) The token is returned from the IP STS to CardSpace (RSTR)

8) Using the token from the IP STS, makes a request for a token from the RP STS (RST)

9) A token is returned to CardSpace (RSTR)

10) CardSpace returns the token to the site


Figure 7

For an example that you can try, check out the age sts at Identity Lab. The page requests the claim ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/age’ (this is just a made up claim URI and not defined anywhere) from an RP STS; that is, the age STS. The age STS requests a self-issued card with the claim ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/DateOfBirth’. When a user goes to the page, she needs to submit a self-issued card, which contains a ‘Date of Birth’ claim. This is sent to the age STS, which calculates age and creates a new token, which is returned to the web site. The web site then shows the claim values it has received, in this case, the age. In this scenario, the age STS is playing the role of a claim transformer, as described in the Identity Metasystem.

As previously stated, the RP STS’s policy is used for card matching. Similarly, if the RP STS requests a PPID, it is the RP STS certificate that is used for calculating the PPID, not the certificate of the RP site. This is so a single RP STS can service multiple sites, but always gets the same PPID for a given user from CardSpace.

The certificate information CardSpace shows the user is that of the RP site, even though the policy is used from the RP STS. This may seem somewhat contradictory, however since the RP site is truly the site the user is visiting; the user needs to make a trust decision about it. If the site chooses to use a RP STS, this is more an implementation detail, and by choosing to trust the RP site, the user indirectly trusts the services that site chooses to use.

In addition to the RP site cert getting shown in CardSpace, it is also used to track card usage history. So if a card is used at two different RP sites that rely on the same RP STS, two separate entries will be created in the card history.

The astute reader may notice I’ve only handled cases where the RP site and RP STS have a certificate, and may wonder what would happen if the RP web site uses HTTP, which now works with CardSpace. The answer is the RP site and RP STS must both have certificates. The support of HTTP only sites was made to help smaller sites that may not have much in the way of security requirements, but still want to use CardSpace. However, the RP STS support is targeted at sites and organizations which have more complex scenarios, for whom the procuring a certificate and using HTTPS for additional security is likely to already be a security requirement.

For the actual STS endpoints HTTPS (transport) is not required, however the binding the STS uses must have a certificate. This could be provided by transport or message security. The examples in this post use message security for the STS endpoints, which is why the STS URLs start with HTTP, yet they still have certificates associated with them.

Ok, now for a quick quiz.

Say there is an RP website that contains the below object tag.


And the policy at the MEX endpoint, ‘https://ipsts.federatedidentity.net/sts.svc/mex’, declares a requirement for a token with the issuer ‘http://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self’ and claim ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname’ and ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname’. That is, the STS is requesting a token from a self-issued card that contains a first and last name.

How is the resulting flow best described?

a) The website is requesting a token from an RP STS. The RP STS is requesting a token from a self-issued card. So the user will see CardSpace UI open and will get to pick which self-issued card to use. The self-issued token is then sent to the RP STS, which generates a token that is sent to the RP web site.

b) The website is requesting a token from an IP STS. CardSpace opens and the user selects the managed card whose issuer is ‘http://ipsts.federatedidentity.net/sts.svc’. Authentication to the IP STS is done with a self-issued card, so on selection of the managed card CardSpace automatically sends the token generated by the correct self-issued card to the IP STS. The token from the IP STS is then sent to the RP site.

c) Not enough information.

This really was kind of a trick question. The right answer is c) not enough information. It may be tempting to say a) since a MEX endpoint is defined in the object tag. However, IP STSs have MEX endpoints as well, it just isn’t necessary to include them in the object tag for IP STSs, since the MEX endpoint is also defined in the managed card. So the presence of a MEX endpoint in the object tag is only required when using an RP STS, but does not guarantee that an RP STS is being referred to. If you think about it, it would seem strange for the RP site to be the one dictating if the next STS in the chain is an IP STS or RP STS; that decision should authoritatively be made and expressed by the STS itself. Still, it is probably good practice not to specify the MEX endpoint (issuerPolicy) for an IP STS, since the MEX call will need to be made again anyway when the managed card is used, and just calling once will be faster. Also, not including the MEX endpoint makes it so the RP site won’t be affected if the MEX URL changes for any reason.

That leaves the obvious question. If there wasn’t enough information, what other information is needed? The answer lies in the MEX policy of the STS. If it is an IP STS, it will have the element <ic:RequireFederatedIdentityProvisioning xmlns:ic=”http://schemas.xmlsoap.org/ws/2005/05/identity” /> in its policy. The following description of RequireFederatiedIdentityProvisioning appears in Identity Selector Interoperability Profile V1.0

This element indicates a requirement that one or more information cards, representing identities that can be federated, must be pre-provisioned before token requests can be made to the identity provider.

In other words, the element is placed at federation boundaries. When crossing a trust boundary it makes sense that a user interaction may occur, and cards are great way for the user to be involved. Back in figure 4, the box drawn with the dashed line represents a trust boundary around the RP. All sites and STSs in the boundary often don’t require user interaction when communicating with each other, since all tokens passed around are within an organization. Also since it is between parties in the same organization, there should not be any privacy concerns. However, as soon as the boundary is hit, as in the case of federation, it makes sense for the user to be prompted. Note, in most cases this boundary will be between organizations, but it could even be in an organization if the information being passed is not already freely shared between the group running the RP STS and RP site.

This element was described in a fairly straightforward scenario, but it is actually required to resolve ambiguities in many cases, such as in the case that a web service is accessed by an application using the WCF stack, the stack needs to have a way to know if CardSpace should be invoked. The credential required to authenticate to the final STS in a chain can be collected in other ways than just CardSpace, such as when the credentials of the currently logged in user are used, or the user is prompted directly for username and password through some custom application. If the RequireFederatedIdentityProvisioning element is in the last policy in a policy chain (or one from the last), CardSpace will be called.

WCF developers may be wondering how to set RequireFederatedIdentityProvisioning in policy, from config. It is done by using the <useManagedPresentation> binding element.

In Summary

Hopefully this provides a good reference for people interested in understanding RP STS.

I’ve tried to give a quick explanation of what a RP STS is, as well as a case in which it may be used. I think some of the key take-away points are:

1) CardSpace also works with RP STSs, which consume the tokens represented by cards.

2) There can be multiple RP STSs in a chain.

3) CardSpace must be given the MEX endpoint URL of an RP STS, either from the WCF app config or from the issuerPolicy element in the x-informationCard object tag for browser applications.

4) Each RP STS needs a certificate, and the web site making the initial request must use HTTPS.

5) <RequireFederatedIdentityProvisioning> is the hint to CardSpace that an STS is an IP STS – not an RP STS.

Please let me know if you have any questions, or can think of any CardSpace topics that could use some more documentation.



Comments (6)

  1. kingbing says:

    Wow. Great post, thanks. Between this and Vittorio’s post, I’m all sorted on IP and RP STSes.

    Unfortunately, it now raises a couple of questions about RequiresFederatedIdentityProvisioning. This is something I’m finding difficult to wrap my head around. I wonder if you there’s another post needed just for this subject.

    Let me try and talk through what I think happens. If the policy for STS1 states it requires an IssuedToken from STS2, CardSpace (or an alternative WS stack, such as WCF) will retrieve the policy for STS2. If that policy states it needs an IssedToken for STS3, the policy for STS3 is retrieved.

    Is RequireFederatedIdentityProvisioning an indication that the WS stack should stop retrieving policies and prompt the user to resolve the current policy? Or is it really an indication that this STS requires a managed card? (Are they the same thing?)

    Thinking out loud, I could simply keep resolving policies until I reached an STS policy that no longer required an IssuedToken but a username token, X059 cert or Kerberos ticket. I could then display the identity selector to resolve the current policy, picking a card that matches the current issuer and required claims (if one exists), and getting prompted for username, smart card, etc. And the current STS might well be the self-issued card STS.

    Why would I need a policy element to tell me to prompt the user when I can just keep resolving until I hit the last STS?

    The only reasons I can think of are:

    1. Using an alternative stack, I wouldn’t know to display CardSpace, but would prompt the user myself. But then the RequireFederatedIdentityProvisioning becomes DisplayCardSpaceIdentitySelector, which is a little specific…
    2. The algorithm relies of a known set of "final", unresolvable tokens (username, x509, etc) Future expansion is made more difficult

    3. Picking a different identity earlier in the chain. If I’m trying to log onto my bank, and they give me a managed card backed by a self-issued card, would I want to pick the managed card from my bank, or the self-issued card I’d backed it with? In my simple algorithm, I’d have to select the self-issued card. What happens if I have 2 managed cards? What if both managed cards are backed by the same self-issued card?

    I think this last one is the clincher for me. If the bank’s STS specifies RequireFederatedIdentityProvisioning, I know that the user has a managed card, and should let them choose which one. If that choice then requires more resolving, I do so after the choice.

    Am I anywhere near right?

    Sorry for rambling, but this is a subtle topic that I’m finding difficult to properly understand. Plus it’s really interesting. Great post, please keep them coming!



    PS. The docs for <useManagedPresentation> are a bit poor: "Represents a binding element that specifies that managed presentation to be used. This element has no attribute and is present as an empty switch." Nowhere near as useful as this post…

  2. Thanks for asking the clarifying questions, I’ll add a new post to try and explain RequireFederatedIdentityProvisioning.  To quickly answer some of your questions.

    First, you say  ‘CardSpace (or an alternative WS stack, such as WCF)’.  I understand what you are saying here, but just to be clear, CardSpace is not a WS stack.  In the browser case, it contains the logic to follow the policy chain, but it sits upon WCF when it does it, making WCF calls to retrieve policy and make the token requests.

    I’d say RequireFederatedIdentityProvisioningis really a hint that the STS that has this element in its policy should be accessed via a pre-provisioned card, and in most cases this means user interaction as well.  So the user needs to have a managed card to use the STS (by use I mean get a token from the STS that can be used to auth to another STS or RP).

    Say the policy ends by requiring a Kerberos ticket.  Even in a WCF scenario, there is no guarantee that CardSpace should be called without the RequireFederatedIdentityProvisioning element being present.  It could be that auth is done with no user interaction, in many cases inside an organization this might be desirable.  Similarly for username/password and X509 auth, the WCF application could provide a custom UI for collecting credentials, so again, no CardSpace should show.  

    In all of these cases, when called from the browser and CardSpace follows the chains,  it could ignore the elements and behave as you suggest.  But there is a nice architectural consistency to have the same behavior in both cases.

    Now for the self-issued backed card case, I think the element is critical even in the browser scenario, since it differentiates between the RP STS and IP STS scenario ( I explain this one in more detail in the post when I introduce RequireFederatedIdentityProvisioning)

    Yep absolutely want to avoid any reference in the protocol that is CardSpace specific.  So DisplayCardSpaceIdentitySelector is out, maybe UseInformationCardIdentitySelector would probably work, but without a major need to rename it probably won’t happen now.

    You are right on with your second point, it makes additions in the future easier.

    Your point 3 is good to, similar to the one I was making about wanting to be able to have a difference between a RP STS that accepts a self-issued card and an IP STS that accepts a self-issued card.

    I very much appreciate the questions.  It is subtle, I’ve explained in several times both inside and outside of MS, so really want to get the post to be as helpful as possible.



  3. Pedro Felix says:


    This is a very interesting post, dealing with some questions for which I don’t have a clear answer.

    First of all, when does the “chase” of the policy chain ends? The specs, namely [1], don’t deal with this issue and I’ve seen different answers to this question, namely:

    a)  http://blogs.msdn.com/vbertocci/archive/2007/09/24/the-resource-sts-r-sts-rp-sts-a-sts-the-other-face-of-token-issuing.aspx

    “When the selector encounters such an element, it will fetch (via WS-MetadataExchange) the policy of the resource STS. If that policy happen to be satisfied by one or more cards (…) owned by the user, the identity selector will pop up”

    b)  http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=1668019&SiteID=1

    “The policy traversal ends when either of following is seen:

    1. The IssuedToken being asked for has issuer as self (http://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self), anonymous, or not specified
    2. issuedtoken whose mex address is unavailable or not specified

    3. credential being asked for is not a issued-token (like username/X509/Kerberos) in managed card case”

    Does the policy chain “chase” stops when exists a card “satisfying” the policy requirements?

    Shouldn’t this behavior be clearly described in the infocard specs ([1]) for all identity selectors? Or is this an issue that can be handled differently by each identity selector?



    [1] “A Guide to the Identity Selector Interoperability Profile V1.0“, April, 2007

  4. Pedro Felix says:

    Hello again.

    I’ve a couple of comments regarding your statement “by choosing to trust the RP site, the user indirectly trusts the services that site chooses to use”

    Consider the following scenario:

    1) An RP requires a token issued by a third party “age STS” (similar to the one at Identity Lab), containing an “age” claim. However, the organizations running the RP and the “age STS” are not the same.

    2) This third party “age STS” requires a token issued from an IP, containing a “DateOfBirth” claim.

    3) A user U has a managed token from this IP.

    When the CardSpace requests the disclosure authorization from the user U, it presents the following information: the claim is “DateOfBirth” and the requesting site is RP.

    However, the trust relation that U has with RP and with “age STS” can be very different.

    Namely, consider the scenario where user U “trusts” “age STS” enough to reveal its date of birth but do not “trusts” RP enough to disclosure the same type of information. In this situation, the information presented by the CardSpace UI will be misleading.

    In my opinion, this problem arises because the “age STS” is not really a “RP STS”. Instead, its role is of a “third party claim transformer”, which isn’t necessarily the same: a “RP STS” is an RP-side implementation detail (they are inside the same boundary); a “third party claim transformer” cannot be considered an implementation detail and must be explicitly considered on the user’s trust decision.

    Am I missing something here?



  5. Thanks for the good questions Pedro.  I’m just getting back in after the holidays, but will write another post soon to try and address them.



  6. Anonymous says:

    A useful, yet sparsely documented feature of Windows CardSpace is its support for resource side Security Token Services (STSs) &amp;#8211; STSs that are used by relying parties rather than Identity Providers. Vittorio has done an excellent job helping