Appendix B

The Browser-Based Scenario - Step 1, Step 2, Step 3, Step 4, Step 5, Step 6, Step 7 | The Active Client Scenario - Step 1, Step 2 | The Browser-Based Scenario with Access Control Service (ACS) - Step 1, Step 2, Step 3, Step 4, Step 5, Step 6, Step 7, Step 8, Step 9, Step 10, Step 11, Step 12 | Single Sign-Out - Step 1, Step 2, Step 3, Step 4, Step 5, Step 6, Step 7, Step 8, Step 9, Step 10, Step 11, Step 12, Steps 13 and 14

Appendix B shows in detail the message sequences for the passive (browser-based) and active (smart) client scenarios. It also includes information about what the HTTP and, where applicable, Kerberos, traffic looks like as the browser or client, the application, the issuer, and Microsoft® Active Directory® directory service communicate with each other.

The Browser-Based Scenario

Figure 1 shows the message sequence for the browser-based scenario.

Figure 1

Message sequence for the browser-based scenario

Figure 2 shows the traffic generated by the browser.

Figure 2

HTTP traffic

The numbers in the screenshot correspond to the steps in the message diagram. In this example, the name of the application is a-Expense.ClaimsAware. For example, step 1 in the screen shot shows the initial HTTP redirect to the issuer that is shown in the message diagram. The following table explains the symbols in the "#" column.

Symbol	Meaning
Arrow	An arrow indicates an HTTP 302 redirect.
Key	A key indicates a Kerberos ticket transaction (the 401 code indicates that authentication is required).
Globe	A globe indicates a response to a successful request, which means that the user can access a website.

Step 1

The anonymous user browses to a-Expense and the Federation Authentication Module (FAM), WSFederatedAuthenticationModule, redirects the user to the issuer which, in this example, is located at https://login.adatumpharma.com/FederationPassive. As part of the request URL, there are four query string parameters: wa (the action to execute, which is wsignin1.0), wtrealm (the relying party that this token applies to, which is a-Expense), wctx (context data such as a return URL that will be propagated among the different parties), and wct (a time stamp).

Figure 3 shows the response headers for step 1.

Figure 3

Response headers for step 1

The FAM on a-Expense redirects the anonymous user to the issuer.

Figure 4 shows the parameters that are sent to the issuer with the query string.

Figure 4

Query string parameters

Step 2

The issuer is Active Directory Federation Services (ADFS) 2.0 configured with Integrated Windows® Authentication only. Figure 5 shows that ADFS redirects the user to the integrated sign-on page.

Note

ADFS can be configured to allow Integrated Windows Authentication and/or client certificate authentication and/or forms-based authentication. In either case, credentials are mapped to an Active Directory account.

Figure 5

ADFS redirecting the user to the Integrated Windows Authentication page

Step 3

The IntegratedSignIn.aspx page is configured to use Integrated Windows Authentication on Microsoft Internet Information Services (IIS). This means that the page will reply with an HTTP 401 status code and the "WWW-Authenticate: Negotiate" HTTP header. This is shown in Figure 6.

Figure 6

ADFS returning WWW-Authenticate: Negotiate header

IIS returns the WWW-Authenticate:Negotiate header to let the browser know that it supports Kerberos or NTLM.

Step 4

At this point, the user authenticates with Microsoft Windows credentials, using either Kerberos or NTLM. Figure 7 shows the HTTP traffic for NTLM, not Kerberos.

Note

If the infrastructure, such as the browser and the service principal names, are correctly configured, the client can avoid step 4 by requesting a service ticket from the key distribution center that is hosted on the domain controller. It can then use this ticket together with the authenticator in the next HTTP request.

Figure 7

NTLM handshake on the ADFS website

The Cookies/Login node for the request headers shows the NTLM handshake process. This process has nothing to do with claims, WS-Federation, Security Assertion Markup Language (SAML), or WS-Trust. The same thing would happen for any site that is configured with Integrated Windows Authentication. Note that this step does not occur for Kerberos.

Step 5

Now that the user has been successfully authenticated with Microsoft Windows credentials, ADFS can generate a SAML token based on the Windows identity. ADFS looks up the claims mapping rules associated with the application using the wtrealm parameter mentioned in step 1 and executes them. The result of those rules is a set of claims that will be included in a SAML assertion and sent to the user's browser.

The following XML code shows the token that was generated (some attributes and namespaces were deleted for clarity).

<t:RequestSecurityTokenResponse 
  xmlns:t="https://schemas.xmlsoap.org/ws/2005/02/trust">
  <t:Lifetime>
    <wsu:Created>2009-10-22T14:40:07.978Z</wsu:Created>
    <wsu:Expires>2009-10-22T00:40:07.978Z</wsu:Expires>
  </t:Lifetime>
  <wsp:AppliesTo>
    <EndpointReference>
      <Address>

        https://www.adatumpharma.com/a-Expense.ClaimsAware/
      </Address>
    </EndpointReference>
  </wsp:AppliesTo>
  <t:RequestedSecurityToken>

    <saml:Assertion 
        MinorVersion="1" 
        AssertionID="_9f68..." Issuer="http://.../Trust">
      <saml:Conditions 
        NotBefore="2009-10-22T14:40:07.978Z" 
        NotOnOrAfter="2009-10-22T00:40:07.978Z">
        <saml:AudienceRestrictionCondition>
          <saml:Audience>
            https://www.adatumpharma.com/a-Expense.ClaimsAware/
          </saml:Audience>
        </saml:AudienceRestrictionCondition>
      </saml:Conditions>
      <saml:AttributeStatement>
        <saml:Subject>
          <saml:SubjectConfirmation>
            <saml:ConfirmationMethod>
               urn:oasis:names:tc:SAML:1.0:cm:bearer
            </saml:ConfirmationMethod>
          </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Attribute 
           AttributeName="name"  
           AttributeNamespace=
               "http://.../ws/2005/05/identity/claims">
          <saml:AttributeValue>
mary</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute 
           AttributeName="CostCenter" 
           AttributeNamespace=
                "http://schemas.adatumpharma.com/2009/08/claims">
          <saml:AttributeValue>
394002</saml:AttributeValue>
        </saml:Attribute>
      </saml:AttributeStatement>
      <ds:Signature>
       <ds:SignedInfo>
       ...
       </ds:SignedInfo>
       <ds:SignatureValue>
          dCHtoNUbvVyz8...n0XEA6BI=
       </ds:SignatureValue>
       <KeyInfo>
         <X509Data>
           <X509Certificate>
             MIIB6DCC...gUitvS6JhHdg
         </X509Certificate>
         </X509Data>
       </KeyInfo>
     </ds:Signature>
    </saml:Assertion>
  </t:RequestedSecurityToken>
  <t:TokenType>
     http://docs.oasis-open.org/wss/
         oasis-wss-saml-token-profile-1.1#SAMLV1.1
  </t:TokenType>
  <t:RequestType>
     https://schemas.xmlsoap.org/ws/2005/02/trust/Issue
  </t:RequestType>
  <t:KeyType>
     https://schemas.xmlsoap.org/ws/2005/05/identity/NoProofKey
  </t:KeyType>
</t:RequestSecurityTokenResponse>

Step 6

Once ADFS generates a token, it needs to send it back to the application. A standard HTTP redirect can't be used because the token may be 4 KB long, which is larger than most browsers' size limit for a URL. Instead, issuers generate a <form> that includes a POST method. The token is in a hidden field. A script auto-submits the form once the page loads. The following HTML code shows the issuer's response.

<html>
  <head>
    <title>Working...</title>
  </head>
  <body>
    <form 
      method="POST" 
      name="hiddenform" 
      action=
        "https://www.adatumpharma.com/a-Expense.ClaimsAware/">
      <input type="hidden" name="wa" value="wsignin1.0" />
      <input 
         type="hidden" 
         name="wresult" 
         value="&lt;t:RequestSecurityTokenResponse   
                  xmlns...&lt;/t:RequestSecurityTokenResponse>" 
      />
      <input 
         type="hidden" 
         name="wctx" 
         value="rm=0&amp;id=passive&amp;
                   ru=%2fa-Expense.ClaimsAware%2fdefault.aspx" 
      />
      <noscript>
        <p>Script is disabled. Click Submit to continue.</p>
        <input type="submit" value="Submit" />
      </noscript>
    </form>
    <script language="javascript">
      window.setTimeout('document.forms[0].submit()', 0);
    </script>
  </body>
</html>

When the application receives the POST, the FAM takes control of the process. It listens for the AuthenticateRequest event. Figure 8 shows the sequence of steps that occur in the handler of the AuthenticateRequest event.

Figure 8

Logic for an initial request to an application

Notice that one of the steps that the FAM performs is to create the session security token. In terms of network traffic, this token is a set of cookies named FedAuth[n] that is the result of compressing, encrypting, and encoding the ClaimsPrincipal object. The cookies are chunked to avoid exceeding any cookie size limitations. Figure 9 shows the HTTP response, where a session token is chunked into three cookies.

Figure 9

HTTP response from the website with a session token chunked into three cookies

Step 7

The session security token (the FedAuth cookies) is sent on subsequent requests to the application. In the same way that the FAM handles the AuthenticationRequest event, the SAM executes the logic shown in Figure 10.

Figure 10

Logic for subsequent requests to the application

The FedAuth cookies are sent on each request. Figure 11 shows the network traffic.

Figure 11

Traffic for a second HTTP request

The Active Client Scenario

The following section shows the interactions between an active client and a web service that is configured to trust tokens generated by an ADFS issuer. Figure 12 shows a detailed message sequence diagram.

Figure 12

Active client scenario message-diagram

Figure 13 shows the corresponding HTTP traffic for the active client message sequence.

Figure 13

HTTP traffic

Following are the two steps, explained in detail.

Step 1

The Orders web service is configured with the wsFederationHttpBinding. This binding specifies a web service policy that requires the client to add a SAML token to the SOAP security header in order to successfully invoke the web service. This means that the client must first contact the issuer with a set of credentials (the user name and password) to get the SAML token. The following message represents a RequestSecurityToken (RST) sent to the ADFS issuer (ADFS) hosted at https://login.adatumpharma.com/adfs/services/trust/13/usernamemixed. (Note that the XML code is abridged for clarity. Some of the namespaces and elements have been omitted.)

<s:Envelope>
  <s:Header>
    <a:Action>
      http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue
    </a:Action>  
    <a:To>
      https://login.adatumpharma.com/adfs/
                                 services/trust/13/usernamemixed
    </a:To>
    <o:Security>
      <o:UsernameToken 
        u:Id="uuid-bffe89aa-e6fa-404d-9365-d078d73beca5-1">
        <o:Username>
          <!-- Removed-->
        </o:Username>
        <o:Password>
          <!-- Removed-->
        </o:Password>
      </o:UsernameToken>
    </o:Security>
  </s:Header>
  <s:Body>
    <trust:RequestSecurityToken 
      xmlns:trust=
              "http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wsp:AppliesTo>
        <EndpointReference>
          <Address>
             https://orders.adatumpharma.com/Orders.svc
          </Address>
        </EndpointReference>
      </wsp:AppliesTo>
      <trust:TokenType>
         http://docs.oasis-open.org/wss/
            oasis-wss-saml-token-profile-1.1#SAMLV1.1
      </trust:TokenType>
      <trust:KeyType>
         http://docs.oasis-open.org/ws-sx/
                                     ws-trust/200512/SymmetricKey
    </trust:KeyType>
    </trust:RequestSecurityToken>
  </s:Body>
</s:Envelope>

The issuer uses the credentials to authenticate the user and executes the corresponding rules to obtain user attributes from Active Directory (or any other attributes store it is configured to contact).

<s:Envelope>
  <s:Header>
    <a:Action>http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/IssueFinal</a:Action>
  </s:Header>
  <s:Body>
    <trust:RequestSecurityTokenResponseCollection xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <trust:RequestSecurityTokenResponse>
        <trust:Lifetime>
          <wsu:Created>2009-10-22T21:15:19.010Z</wsu:Created>
          <wsu:Expires>2009-10-22T22:15:19.010Z</wsu:Expires>
        </trust:Lifetime>
        <wsp:AppliesTo>
          <a:EndpointReference>
            <a:Address>
               https://orders.adatumpharma.com/Orders.svc
            </a:Address>
          </a:EndpointReference>
        </wsp:AppliesTo>
        <trust:RequestedSecurityToken>
          <xenc:EncryptedData>
            <xenc:EncryptionMethod 
              Algorithm=
                 "http://www.w3.org/2001/04/xmlenc#aes256-cbc" />
            <KeyInfo>
              <e:EncryptedKey>
                <KeyInfo>
                  <o:SecurityTokenReference>
                    <X509Data>
                      <X509IssuerSerial>
                        <X509IssuerName>
                           CN=localhost
                        </X509IssuerName>
                        <X509SerialNumber>
                         -124594669148411034902102654305925584353
                        </X509SerialNumber>
                      </X509IssuerSerial>
                    </X509Data>
                  </o:SecurityTokenReference>
                </KeyInfo>
                <e:CipherData>                    <e:CipherValue>
                        WayfmLM9DA5....u17QC+MWdZVCA2ikXwBc=
                   </e:CipherValue>
                </e:CipherData>
              </e:EncryptedKey>
            </KeyInfo>
            <xenc:CipherData>
              <xenc:CipherValue>
                  U6TLBMVR/M4Ia2Su....../oV+qg/VU=
              </xenc:CipherValue>
            </xenc:CipherData>
          </xenc:EncryptedData>
        </trust:RequestedSecurityToken>
        <trust:RequestedProofToken>
          <trust:ComputedKey>
             http://docs.oasis-open.org/ws-sx/
                                         ws-trust/200512/CK/PSHA1
          </trust:ComputedKey>
        </trust:RequestedProofToken>
        <trust:TokenType>
           http://docs.oasis-open.org/wss/
                 oasis-wss-saml-token-profile-1.1#SAMLV1.1
        </trust:TokenType>
        <trust:KeyType>
           http://docs.oasis-open.org/ws-sx/
                                     ws-trust/200512/SymmetricKey
        </trust:KeyType>
      </trust:RequestSecurityTokenResponse>
    </trust:RequestSecurityTokenResponseCollection>
  </s:Body>
</s:Envelope>

If you had the private key to decrypt the token (highlighted above as "<e:CipherValue>U6TLBMVR/M4Ia2Su..."), the following is what you would see.

<saml:Assertion 
  MajorVersion="1" 
  MinorVersion="1" 
  AssertionID="_a5c22af0-b7b2-4dbf-ac10-326845a1c6df"  
  Issuer="http://login.adatumpharma.com/Trust" 
  IssueInstant="2009-10-22T21:15:19.010Z ">
  <saml:Conditions 
     NotBefore="2009-10-22T21:15:19.010Z " 
     NotOnOrAfter="2009-10-22T22:15:19.010Z ">
     <saml:AudienceRestrictionCondition>
       <saml:Audience>
          https://orders.adatumpharma.com/Orders.svc
       </saml:Audience>
     </saml:AudienceRestrictionCondition>
  </saml:Conditions>
  <saml:AttributeStatement>
    <saml:Subject>
      <saml:SubjectConfirmation>
        <saml:ConfirmationMethod>
          urn:..:SAML:1.0:cm:holder-of-key
        </saml:ConfirmationMethod>
        <KeyInfo>
           <trust:BinarySecret>
              ztGzs3I...VW+6Th38o=
           </trust:BinarySecret>
        </KeyInfo>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Attribute 
      AttributeName="name" 
      AttributeNamespace=           
         "https://schemas.xmlsoap.org/ws/2005/05/identity/claims">
      <saml:AttributeValue>rick</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute 
      AttributeName="role" 
      AttributeNamespace=
       "https://schemas.xmlsoap.org/ws/2005/05/identity/claims">
      <saml:AttributeValue>OrderTracker</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
  <ds:Signature>
    <ds:SignedInfo> ... </ds:SignedInfo>
      <ds:SignatureValue>
          dCHtoNUbvVyz8...n0XEA6BI=
      </ds:SignatureValue>
            <KeyInfo>
        <X509Data>
          <X509Certificate>
            MIIB6DCC...gUitvS6JhHdg
          </X509Certificate>
        </X509Data>
      </KeyInfo>
   </ds:Signature>
</saml:Assertion>

Step 2

Once the client obtains a token from the issuer, it can attach the token to the SOAP security header and call the web service. This is the SOAP message that is sent to the Orders web service.

<s:Envelope>
  <s:Header>
    <a:Action>http://tempuri.org/GetOrders</a:Action>
    <a:To>https://orders.adatumpharma.com/Orders.svc</a:To>
    <o:Security>
      <u:Timestamp u:Id="_0">
        <u:Created>2009-10-22T21:15:19.123Z</u:Created>
        <u:Expires>2009-10-22T21:20:19.123Z</u:Expires>
      </u:Timestamp>
      <xenc:EncryptedData >
        ... the token we’ve got in step 1 ...
      </xenc:EncryptedData>
      <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        ...
        <SignatureValue>
          oaZFLr+1y/I2kYcAvyQv6WSkPYk=
        </SignatureValue>
        <KeyInfo>
          <o:SecurityTokenReference>
            <o:KeyIdentifier 
               ValueType=
                 "http://docs.oasis-open.org/wss/
                    oasis-wss-saml-token-profile-1.0#
                    SAMLAssertionID">
              _a5c22af0-b7b2-4dbf-ac10-326845a1c6df
            </o:KeyIdentifier>
          </o:SecurityTokenReference>
        </KeyInfo>
      </Signature>
    </o:Security>
  </s:Header>
  <s:Body>
    <GetOrders xmlns="http://tempuri.org/">
      <customerId>1231</customerId>
    </GetOrders>
  </s:Body>
</s:Envelope>

Windows Identity Foundation (WIF) and Windows Communication Foundation (WCF) will take care of decrypting and validating the SAML token. The claims will be added to the ClaimsPrincipal object and the principal will be added to the WCF security context. The WCF security context will be used in the authorization manager by checking the incoming claims against the operation call the client wants to make.

The Browser-Based Scenario with Access Control Service (ACS)

Figure 14 shows the message sequence for the browser-based scenario that authenticates with a social identity provider and uses ACS for protocol transition.

Figure 14

Message sequence for the browser-based scenario with ACS and authentication with a social identity provider

Figure 15 shows the key traffic generated by the browser. For reasons of clarity, we have removed some messages from the list.

Figure 15

HTTP traffic

The numbers in the screenshot correspond to the steps in the message diagram. In this sample, the name of the application is a-Order.Tracking.6 and it is running on the local machine. The name of the mock issuer that takes the place of ADFS is Adatum.FederationProvider.6 and it is also running locally, and the name of the ACS instance is federationwithacs-dev.accesscontrol.windows.net. The sample illustrates a user authenticating with a Google identity.

Step 1

The anonymous user browses to a-Order.OrderTracking.6, and because there is no established security session, the WSFederatedAuthenticationModule (FAM) redirects the browser to the issuer which, in this example is located at https://localhost/Adatum.FederationProvider.6/. As part of the request URL, there are four query string parameters: wa (the action to execute, which is wsignin1.0), wtrealm (the relying party that this token applies to, which is a-Order.OrderTracking), wctx (context data, such as a return URL that will be propagated among the different parties), and wct (a time stamp).

Figure 16 shows the response headers for step 1.

Figure 16

Response headers for step 1

Figure 17 shows the parameters that are sent to the issuer with the query string.

Figure 17

Query string parameters

Step 2

The issuer is a simulated issuer that takes the place of ADFS for this sample. Figure 18 shows that the simulated issuer redirects the user to the home realm discovery page where the user can select the identity provider she wants to use.

Note

The simulated issuer is built using the WIF SDK.

Figure 18

Simulated issuer redirecting the user to the HomeRealmDiscovery page

Step 3

On the home-realm discovery page, the user can elect to sign in using the Adatum provider, the Litware provider, or a social identity provider. In this walkthrough, the user opts to use a social identity provider and provides an email address. When the user submits the form, the simulated issuer parses the email address to determine which social identity provider to use.

Step 4

The home-realm discovery page redirects the browser to the Federation.aspx page.

Step 5

The Federation.aspx page at the simulated issuer returns a cookie to the browser that stores the original wa, wtrealm, wctx, and wct querystring parameters, as was shown in Figure 17. The simulated issuer redirects the user to the ACS instance, passing new values for these parameters. The simulated issuer also sends a whr querystring parameter; this is a hint to ACS about which social identity provider it should use to authenticate the user. Figure 19 shows that the simulated issuer redirects the user to ACS.

Figure 19

The simulated issuer redirects the user to ACS

Figure 20 shows the new values of the querystring parameters that the simulated issuer sends to ACS. This includes the value "Google" for the whr parameter. The value of the wctx parameter refers to the cookie that contains the original values of the wa, wtrealm, wctx, and wct querystring parameters that came from the relying party—a-Order.OrderTracking.

Figure 20

Querystring parameters sent to ACS from the simulated issuer

Step 6

ACS verifies that the wtrealm parameter value, https://localhost/Adatum.FederationProvider.6, is a configured relying party application. ACS then examines the whr parameter value to determine which identity provider to redirect the user to. If there is no valid whr value, then ACS will display a page listing the available identity providers. ACS forwards the wtrealm parameter value to Google in the opened.return_to parameter, so that when Google returns a token to ACS, it can tell ACS the address of the relying party (for ACS, the relying party is https://localhost/Adatum.FederationProvider.6.)

Step 7

Google displays a login form that prompts the user to provide credentials. This form also indicates to the user that the request came from ACS.

Step 8

After Google has authenticated the user and obtained consent to return the users email address to the relying party (ACS), Google redirects the browser back to ACS.

Figure 21 shows the querystring parameters that Google uses to pass the claims back to ACS.

Figure 21

Querystring parameters sent from Google to ACS

In addition to the claims data, there is also a context parameter that enables ACS to associate this claim data with the original request from a-Order.OrderTracking.6. This context parameter includes the address of the Adatum simulated issuer, which sent the original request to ACS.

Step 9

ACS transitions the token from Google to create a new SAML 1.1 token, which contains a copy of the claims that Google issued. ACS uses the information in the context parameter to identify the relying party application (Adatum.FederationProvider.6) and the rule group to apply. In this sample, the rule group copies all of the claims from Google through to the new SAML token.

The following XML code shows the token that ACS generates (some attributes and namespaces were deleted for clarity).

<t:RequestSecurityTokenResponse 
  Context="6d67cfce-9797-4958-ae3c-1eb489b04801"
  xmlns:t="https://schemas.xmlsoap.org/ws/2005/02/trust">
  <t:Lifetime>
    <wsu:Created>2011-02-09T15:05:17.355Z</wsu:Created>
    <wsu:Expires>2011-02-09T15:15:17.355Z</wsu:Expires>
  </t:Lifetime>

  <wsp:AppliesTo>
    <EndpointReference>
            <Address>
        https://localhost/Adatum.FederationProvider.6/
      </Address>
    </EndpointReference>
  </wsp:AppliesTo>

  <t:RequestedSecurityToken>
    <saml:Assertion 
      AssertionID="_592d..." 
      Issuer="https://federationwithacs-dev.accesscontrol.windows.net/">
      <saml:Conditions 
        NotBefore="2011-02-09T15:05:17.355Z" 
        NotOnOrAfter="2011-02-09T15:15:17.355Z">
        <saml:AudienceRestrictionCondition>
                    <saml:Audience>
            https://localhost/Adatum.FederationProvider.6/
          </saml:Audience>
        </saml:AudienceRestrictionCondition>
      </saml:Conditions>

      <saml:AttributeStatement>
        <saml:Subject>
          <saml:NameIdentifier>
            https://www.google.com/accounts/o8/id?id=AItOawnvknktThEaScLj34MPreTLfOKqrQazL20
          </saml:NameIdentifier>
          <saml:SubjectConfirmation>
            <saml:ConfirmationMethod>
              urn:oasis:names:tc:SAML:1.0:cm:bearer
            </saml:ConfirmationMethod>
          </saml:SubjectConfirmation>
        </saml:Subject>

        <saml:Attribute 
          AttributeName="emailaddress" 
          AttributeNamespace=
          "https://schemas.xmlsoap.org/ws/2005/05/identity/claims">
          <saml:AttributeValue>mary@gmail.com</saml:AttributeValue>
        </saml:Attribute>

        <saml:Attribute
          AttributeName="name"          
          AttributeNamespace="https://schemas.xmlsoap.org/ws/2005/05/identity/claims">
          <saml:AttributeValue>Mary</saml:AttributeValue>
        </saml:Attribute>

        <saml:Attribute
          AttributeName="identityprovider"
          AttributeNamespace="...">
        <saml:AttributeValue>Google</saml:AttributeValue>
      </saml:Attribute>
      </saml:AttributeStatement>

      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
          ...
        </ds:SignedInfo>
        <ds:SignatureValue>
          euicdW...UGM7rA==
        </ds:SignatureValue>
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
          <X509Data>
            <X509Certificate>
              MIIDO...jVSbv/3
            </X509Certificate>
          </X509Data>
        </KeyInfo>
      </ds:Signature>
    </saml:Assertion>
  </t:RequestedSecurityToken>
  <t:RequestedAttachedReference>
    <o:SecurityTokenReference>
      <o:KeyIdentifier 
        ValueType=
        "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID">
        _592d8e3a-8f42-4f14-9552-4617959dbd77
      </o:KeyIdentifier>
    </o:SecurityTokenReference>
  </t:RequestedAttachedReference>
  <t:RequestedUnattachedReference>
    <o:SecurityTokenReference>
      <o:KeyIdentifier 
        ValueType=
        "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID">
        _592d8e3a-8f42-4f14-9552-4617959dbd77
      </o:KeyIdentifier>
    </o:SecurityTokenReference>
  </t:RequestedUnattachedReference>
  <t:TokenType>
    urn:oasis:names:tc:SAML:1.0:assertion
  </t:TokenType>
  <t:RequestType>
    https://schemas.xmlsoap.org/ws/2005/02/trust/Issue
  </t:RequestType>
  <t:KeyType>
    https://schemas.xmlsoap.org/ws/2005/05/identity/NoProofKey
  </t:KeyType>
</t:RequestSecurityTokenResponse>

This step returns a form to the browser with an HTTP 200 status message. The user does not see this form because a JavaScript timer automatically submits the form, posting the new token to the Adatum simulated issuer. It obtains the address of the simulated issuer from the Return URL setting in the Adatum.SimulatedIssuer relying party definition in ACS. The token data is contained in the hidden wresult field. The following HTML code shows the form that ACS returns to the browser. Some elements have been abbreviated for clarity.

<html>
<head>
    <title>Working...</title>
</head>
<body>
  <form method="POST" 
    name="hiddenform" 
    action="https://localhost/Adatum.FederationProvider.6/Federation.aspx">
    <input type="hidden" name="wa" value="wsignin1.0" />
    <input type="hidden" name="wresult"
        value="&lt;t:RequestSecurityTokenResponse Context=&quot;..." />
    <input type="hidden" name="wctx" value="6d67cfce-9797-4958-ae3c-1eb489b04801" />
    <noscript>
      <p>
        Script is disabled. Click Submit to continue.
      </p>
      <input type="submit" value="Submit" />
    </noscript>
  </form>
  <script language="javascript">
      window.setTimeout('document.forms[0].submit()', 0);
  </script>
</body>
</html>

Step 10

The Adatum simulated issuer applies the claims mapping rules to the claims that it received from ACS. The following XML code shows the token that ACS generates (some attributes and namespaces were deleted for clarity).

<trust:RequestSecurityTokenResponseCollection 
  xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
  <trust:RequestSecurityTokenResponse 
    Context="rm=0&amp;id=passive&amp;ru=%2fa-Order.OrderTracking%2f">
    <trust:Lifetime>
      <wsu:Created>2011-02-09T15:05:17.776Z</wsu:Created>
      <wsu:Expires>2011-02-09T16:05:17.776Z</wsu:Expires>
    </trust:Lifetime>
    <wsp:AppliesTo>
      <EndpointReference>
        <Address>
          https://localhost/a-Order.OrderTracking.6/
        </Address>
      </EndpointReference>
    </wsp:AppliesTo>
    <trust:RequestedSecurityToken>
      <saml:Assertion
        AssertionID="_3770..." 
        Issuer="adatum" 
        IssueInstant="2011-02-09T15:05:17.776Z" 
        xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
        <saml:Conditions 
          NotBefore="2011-02-09T15:05:17.776Z" 
          NotOnOrAfter="2011-02-09T16:05:17.776Z">
          <saml:AudienceRestrictionCondition>
            <saml:Audience>
              https://localhost/a-Order.OrderTracking.6/
            </saml:Audience>
          </saml:AudienceRestrictionCondition>
        </saml:Conditions>
        <saml:AttributeStatement>
          <saml:Subject>
            <saml:SubjectConfirmation>
              <saml:ConfirmationMethod>
                urn:oasis:names:tc:SAML:1.0:cm:bearer
              </saml:ConfirmationMethod>
            </saml:SubjectConfirmation>
          </saml:Subject>
          <saml:Attribute
            AttributeName="name"
            AttributeNamespace="..."
            a:OriginalIssuer="acs\Google">
            <saml:AttributeValue>
              Mary
            </saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute 
            AttributeName="role" 
            AttributeNamespace="https://schemas.microsoft.com/ws/2008/06/identity/claims">
            <saml:AttributeValue>
              Order Tracker
            </saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute 
            AttributeName="organization" 
            AttributeNamespace="http://schemas.adatum.com/claims/2009/08">
            <saml:AttributeValue>
              Contoso
            </saml:AttributeValue>
          </saml:Attribute>
        </saml:AttributeStatement>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
          <ds:SignedInfo>
            ...
          </ds:SignedInfo>
          <ds:SignatureValue>ZxLyG...2uU=</ds:SignatureValue>
          <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
            <X509Data>
              <X509Certificate>MIIB5...2B3AO</X509Certificate>
            </X509Data>
          </KeyInfo>
        </ds:Signature>
      </saml:Assertion>
    </trust:RequestedSecurityToken>
    <trust:RequestedAttachedReference>
      <o:SecurityTokenReference 
        k:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" >
        <o:KeyIdentifier
          ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID">
          _377035cf-c44a-4495-a69c-c4b4951af18b
        </o:KeyIdentifier>
      </o:SecurityTokenReference>
    </trust:RequestedAttachedReference>
    <trust:RequestedUnattachedReference>
      <o:SecurityTokenReference 
        k:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1">
        <o:KeyIdentifier 
          ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID">
          _377035cf-c44a-4495-a69c-c4b4951af18b
        </o:KeyIdentifier>
      </o:SecurityTokenReference>
    </trust:RequestedUnattachedReference>
    <trust:TokenType>
      urn:oasis:names:tc:SAML:1.0:assertion
    </trust:TokenType>
    <trust:RequestType>
      http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
    </trust:RequestType>
    <trust:KeyType>
      http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer
    </trust:KeyType>
  </trust:RequestSecurityTokenResponse>
</trust:RequestSecurityTokenResponseCollection>

This step returns a form to the browser with an HTTP 200 status message. The user does not see this form because a JavaScript timer automatically submits the form, posting the new token to the a-Order.OrderTracking.6 application. The token with the new claims is contained in the wresult field. The following HTML code shows the form that ACS returns to the browser. Some elements have been abbreviated for clarity.

<html>
<head>
    <title>Working...</title>
</head>
<body>
  <form method="POST" name="hiddenform" 
        action="https://localhost/a-Order.OrderTracking.6/">
    <input type="hidden" name="wa" value="wsignin1.0" />
    <input type="hidden" name="wresult"
        value="&lt;trust:RequestSecurityTokenResponseCollection..." />
    <input type="hidden" name="wctx" 
           value="rm=0&amp;id=passive&amp;ru=%2fa-Order.OrderTracking%2f" />
    <noscript>
      <p>
        Script is disabled. Click Submit to continue.
      </p>
      <input type="submit" value="Submit" />
    </noscript>
  </form>
  <script language="javascript">
      window.setTimeout('document.forms[0].submit()', 0);
  </script>
</body>
</html>

The simulated issuer determines the address to post the token to (https://localhost/a-Order.OrderTracking.6/) by reading the original value of the wtrealm parameter that the simulated issuer saved in a cookie in step 4.

Step 11

The Federation Authentication Module (FAM) validates the security token from the simulated issuer, and creates a ClaimsPrincipal object using the claim values from the token. This is compressed, encrypted, and encoded to create a session security token which the application returns to the browser as a set of FedAuth[n] cookies. The cookies are chunked to avoid exceeding any cookie size limitations.

Figure 22 shows the response headers, which include the FedAuth cookies.

Figure 22

Response headers, including the FedAuth cookies

Step 12

On subsequent requests to the a-Order.OrderTracking.6 application, the browser returns the security session data to the application. Figure 23 shows the FedAuth cookie in the request headers.

Figure 23

FedAuth cookies in the request header

The WSFederatedAuthenticationModule (FAM) decodes, decrypts, and decompresses the cookie and verifies the security session data before recreating the ClaimsPrincipal object.

Single Sign-Out

Figure 24 shows the single sign-out message sequence for the browser-based scenario.

Figure 24

Message sequence for single sign-out in the browser-based scenario

Figure 25 shows the key traffic generated by the browser. For reasons of clarity, we have removed some messages from the list.

Figure 25

HTTP traffic

The numbers in the screenshot correspond to the steps in the message diagram. In this sample, the names of the two relying party applications are a-Expense.ClaimsAware and a-Order.ClaimsAware and they are running on the local machine. The name of the mock issuer that takes the place of ADFS is Adatum.SimulatedIssuer.1 and it is also running locally. The sample illustrates a user signing in first to a-Expense.ClaimsAware, then accessing the a-Order.ClaimsAware application, and then initiating the single sign-out from a link in the a-Order.ClaimsAware application.

Step 1

The anonymous user browses to a-Expense.ClaimsAware, and because there is no established security session, the WSFederatedAuthenticationModule (FAM) redirects the browser to the issuer which, in this example, is located at https://localhost/Adatum.SimulatedIssuer.1/.

Figure 26

Redirect to the issuer

As part of the request URL, there are four query string parameters: wa (the action to execute, which is wsignin1.0), wtrealm (the relying party that this token applies to, which is a-Expense.ClaimsAware), wctx (this is context data such as a return URL that will be propagated among the different parties), and wct (a time stamp).

Figure 27

WS-Federation data sent to the issuer

Step 2

The simulated issuer allows the user to select a User to sign in as for the session; in this example the user chooses to sign in as John.

Step 3

The simulated issuer stores the name of the relying party (which it can use in the log-out process) in a cookie named AdatumClaimsRPStsSiteCookie, and details of the user in the .WINAUTH cookie.

Figure 28

Cookies containing the user ID and a list of relying parties

The simulated issuer then posts the token back to the a-Expense.ClaimsAware application using a JavaScript timer, passing the WS-Federation token in the wresult field.

Figure 29

Sending the WS-Federation token to the relying party

Step 4

The relying party verifies the token, instantiates a ClaimsPrincipal object, and saves the claim data in a cookie named FedAuth. The application sends an HTTP 302 to redirect the browser to the a-Expense.ClaimsAware website.

Figure 30

Creating the FedAuth cookie in the a-Expense.ClaimsAware application

Step 5

The a-Expense.ClaimsAware application uses the claims data stored in the FedAuth cookie to apply the authorization rules that determine which records John is permitted to view.

Step 6

John clicks on the link to visit the a-Order.ClaimsAware application. From the perspective of the application, the request is from an anonymous user, so it redirects the browser to the simulated issuer.

Figure 31

Redirecting to the issuer

As part of the request URL, there are four query string parameters: wa (the action to execute, which is wsignin1.0), wtrealm (the relying party that this token applies to, which is a-Order.ClaimsAware), wctx (context data, such as a return URL that will be propagated among the different parties), and wct (a time stamp).

Figure 32

WS-Federation data sent to the issuer

Step 7

The simulated issuer recognizes that John is already authenticated because the browser sends the .WINAUTH cookie.

Figure 33

The browser sends the .WINAUTH cookie to the issuer

The application updates the AdatumClaimRPStsSiteCookie with details of the new relying party application, and posts a WS-Federation token back to the relying party.

Figure 34

The browser updates the cookie with the new relying party

Figure 35

The issuer posts the WS-Federation token to the relying party

Step 8

The relying party verifies the token, instantiates a ClaimsPrincipal object, and saves the claim data in a cookie named FedAuth. The application sends an HTTP 302 to redirect the browser to the a-Order.ClaimsAware website.

Figure 36

The a-Order.ClaimsAware site creates a FedAuth cookie

Step 9

The a-Order.ClaimsAware application uses the claims data stored in the FedAuth cookie to apply the authorization rules that determine which records John is permitted to view.

Step 10

John clicks on the Logout link in the a-Order.ClaimsAware application. The application deletes the FedAuth cookie and redirects the browser to the simulated issuer to complete the sign-out process.

Figure 37

Deleting the FedAuth cookie and redirecting to the issuer

Step 11

The simulated issuer redirects the browser to itself, sending a WS-Federation wsignout1.0 command.

Figure 38

Sending the wsignout1.0 command

Step 12

The simulated issuer signs out from any identity providers and deletes the contents of the AdatumClaimsRPStsSiteCookie cookie.

Figure 39

Clearing the cookie with the list of relying parties

Steps 13 and 14

The simulated issuer uses the list of relying parties from the AdatumClaimsRPStsSiteCookie cookie to construct a list of image URLs:

<img src='https://localhost/a-expense.ClaimsAware/?wa=wsignoutcleanup1.0'  /><img src='https://localhost/a-Order.ClaimsAware/?wa=wsignoutcleanup1.0'  />

These URLs pass the WS-Federation wsignoutcleanup1.0 command to each of the relying party applications, giving them the opportunity to complete the sign-out process in the application and perform any other necessary cleanup.

Figure 40

Clearing the FedAuth cookie in the a-Expense.ClaimsAware application

Figure 41

The FedAuth cookie was cleared for the a-Order.Claims application in step 10

Next | Home