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 ‘https://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 ‘https://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 ‘https://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self’ and claim ‘https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname’ and ‘https://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 ‘https://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=” https://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.

Thanks,

Caleb