Creating Managed Cards

Article
06/24/2008

A managed card is an information card issued by an Identity Provider. The managed card contains:

Details about the entity that issues the card, such as:
Card Name
Certificate
Security Token Service (STS) and Metadata Exchange (MEX) endpoints
An image displayed on the card
The list of claims about the user that the Identity Provider corroborates.
Details about how the user authenticates with the STS of the Identity Provider to have the information card populated with the required claim values. This authentication factor can be in the form of a certificate, a Kerberos token, a self-issued card or, in certain cases, a username and password pair.

Note

To create cards for use with CardSpace, the Identity Provider must generate a signed XML file that contains the card data. This information card is named with a .crd file extension.

To work with this sample, Web site configuration is necessary. The configuration is done using the installation batch file provided in the sample folder:

Setup.bat

For more information about installation of the Web site, and some troubleshooting tips, see Installing CardSpace Sample Certificates.

Compiling the Card Writer

The source code for the Card Writer is found in the CardWriter Folder (in C#).

ManagedCardWriter.cs

The source code for the Card Writer is found in the CardWriter Folder (in VB.NET):

ManagedCardWriter.vb

Load the project file (CardWriter.csproj) in Visual Studio 2005 and compile it or use msbuild from the command line (where you unpacked the sample).

msbuild /nologo /v:quiet CardWriter\CardWriter.csproj

This compiles the Card Writer into the \bin folder, which can now be run from the command line.

bin\cardwriter.exe
Usage:
    ManagedCardWriter carddetails.ini [outputfilename.crd]

Using the Card Writer

The card writer uses an .INI file as the input for generating a .CRD file.

bin\cardwriter.exe SampleCards\FabrikamUP.ini
Reading card config from
   <install path >\FabrikamUP.ini
Card written to
   <install path>\SampleCards\FabrikamUP.crd

Note

The output card is placed in the same directory as the source .ini file.

Understanding the data in a CardSpace Card

Inside the source .ini file there are several sections that contain data that can be modified to generate cards for a specific purpose.

Type of card sample

[CARD]
TYPE=UserNamePassword

Using the card creator, each card can use one type of authentication to authenticate with the Identity Provider’s STS. The card type may be one of UserNamePassword, KerberosAuth, SelfIssuedAuth, or SmartCard.

Card Details Sample

[Details]
Name=My Card (U/P backed)
ID=http://www.fabrikam.com/card/unpw/randomnnumber123
version=1
image=images\fabrikam.jpg

In the details section, there are four required fields.

`Name`	The display name of the card that the user sees. The user can modify the name after it is imported into their Identity Selector.
`ID`	This is the ID of the card. Importing cards with the same ID prompts the user about replacing the older card with the newer one. Cards should keep the ID consistent between revisions of their schema.
`Version`	Each new version of the same card should get an incremented version number.
`Image`	The image the user sees on the card when it is imported into their Identity Selector. This cannot be changed by the user.

Issuer Details Sample

[Issuer]
     Address=http://www.fabrikam.com:3074/sts
     MexAddress=https://www.fabrikam.com:4074/sts/mex
     PrivacyPolicy=http://www.fabrikam.com/PrivacyPolicy.xml
     Certificate=LOCALMACHINE/MY/www.fabrikam.com

In the issuer section, there are four required fields.

`Address`	The endpoint URL of the Identity Provider STS.
`MexAddress`	The MEX endpoint for the STS. In CardSpace, HTTPS is required for the MEX endpoint.
`PrivacyPolicy`	The URL for the location of the privacy policy of the Identity Provider.
`Certificate`	The location of the certificate, whose public key, is used to sign the card file. This should be in the format location/store name/common name (for example,localmachine/My/www.fabrikam.com) or a path to a .pfx file that contains the certificate and private key. If the .pfx file is password protected, you must also put a `CertificatePassword`= field in the .ini file.

Claims Details Sample

[Claims]
1=https://schemas.microsoft.com/ws/2005/05/identity/claims/givenname
2=https://schemas.microsoft.com/ws/2005/05/identity/claims/surname   3=https://schemas.microsoft.com/ws/2005/05/identity/claims/emailaddress
4=https://www.contoso.com/myuritest

In the claims section, individual claim URIs are listed that the Identity Provider supports. Use of the standard set of claim URIs requires no additional information, whereas using custom claim URIs requires a section for each custom claim.

Custom Claim URI Details Sample

[https://www.contoso.com/myuritest]
     display=My Super Claim
     description=A claim for all to see

Each custom claim URI must detail the display name and the description for each claim created. These are displayed to the user in the CardSpace Identity Selector.

Token Types Supported Sample

[TokenTypes]
     1=urn:oasis:names:tc:SAML:1.0:assertion
     2=http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1

The Identity Provider declares the types of the tokens that the STS supports. These are listed as URNs in the Token Types section. Each URN is put on a separate line, with an index number as the field name (such as, 1,2,3…).

Token Details Sample

[Token Details]
RequiresAppliesTo=false

The Identity Provider can decide whether to issue tokens to any relying party or may require the relying party to state who they are when requesting the identity.

Credentials

In this section, any credential hint information can be listed and encoded into the card. For different authentication types, there are different possible requirements:

For Self-issued card authentication, the value is the PPID claim from the card, as given to the Identity Provider, using their certificate.
```
[Credentials]
     value=eiavryEeugtsZibaD0moDOiIE+106HbYhYIbst73x5A=
     Hint=Enter your username and password
```
For Username/Password authentication, the value is the username (and is optional), that is displayed for the user.
```
[Credentials]
     value=FrankLee
     Hint=Enter your username and password
```
For Certificate Authentication, you must identify the certificate by one of three methods:
- The thumbprint of the certificate.
- A reference to the certificate in its store in the format location/store name/common name (currentUser/My/FrankLee)
- The hash of the certificate itself.

Certificate Sample

[Credentials]
     value=3ce25c9ef8b2d5d99a227e1ea1a28d7f001a3355
     Hint=Insert your smartcard now

Viewing the Generated Card

The .crd format is an XML document that contains the preceding information. It is used by the Identity Provider to express all those in concise form and it is used by the user for importing the card into their collection.

In this example assume that an Identity Provider is issuing a card that certifies membership in an auto club, and that gives access services or discounts at a variety of Web sites.

The Signature

The root element of the .crd file is an enveloping signature.

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
    <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
    <Reference URI="#_Object_InfoCard">
      <Transforms>
        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
      </Transforms>
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>3x/Op7j/BUjCskLqMHNdfCyI/H8=</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>
      NT...0w==
  </SignatureValue>
  <KeyInfo>
    <X509Data>
      <X509Certificate>
         MIIG…uEd
      </X509Certificate>
      <X509Certificate>
         MIIE...Q==
      </X509Certificate>
    </X509Data>
  </KeyInfo>
  <Object Id="_Object_InfoCard">
      ...
  </Object>
</Signature>

This ensures that once the card has been issued, it should be protected from tampering. This is accomplished with the use of the signature. Additionally, it gives the cryptographic certainty that it is really issued by the auto club, as it shows off usage of the private key.

The two X509Certificate elements contain the certificate of the identity provider (the auto club) and the certificate of the Certifying Authority that issued the certificate to the auto club.

After the signature, there is an element called InformationCard, which contains the actual metadata of the card. The following example shows the XML elements of the card.

<InformationCard xml:lang="en-us" xmlns="https://schemas.microsoft.com/ws/2005/05/identity">
      <InformationCardReference />
      <CardName />
      <CardImage />
      <Issuer />
      <IssuerName />
      <IssuerInformation />
      <TimeIssued />
      <TimeExpires />
      <TokenServiceList />
      <SupportedTokenTypeList />
      <SupportedClaimTypeList />
      <PrivacyNoticeAt />
    </InformationCard>

<InformationCardReference> contains the card ID and the version; used in subsequent import operations so that cards can be updated or overwritten.

<InformationCardReference>
    <CardId>
       http://www.fabrikam.com/card/unpw/randomnnumber123        
    </CardId>
    <CardVersion>1</CardVersion>
 </InformationCardReference>

<CardName> contains the cosmetic card name, which the user is allowed to modify after the import.

<CardName>My Card</CardName>

<CardImage> contains a base64-encoded image that the Identity Provider can select the appearance they prefer. This is encoded inside the card and not referenced in a URL to ensure the provider of the brand consistency without depending on the client’s capability of resolving links.

<CardImage MimeType="image/jpeg">
</CardImage>

<Issuer> represents the URI of the STS—the address to which the Request Security Token (RST) messages are sent every time the managed card is used. <IssuerName> is the cosmetic name associated to it.

<Issuer>http://www.fabrikam.com:3074/sts</Issuer>

<IssuerInformation>, new to .NET Framework 3.5 , contains name-value pairs that allow Identity Providers to bundle ad-hoc information about themselves (for example, how to contact technical support or customer service) into managed cards for display by the client's Information Card Selector.

<IssuerInformation>
    <IssuerInformationEntry>
         <EntryName>Cash Machine Location</EntryName>
         <EntryValue>www.fabrikam.com</EntryValue>
    </IssuerInformationEntry>
    <IssuerInformationEntry>
         <EntryName>Customer Support</EntryName>
         <EntryValue>support.fabrikam.com</EntryValue>
    </IssuerInformationEntry>
</IssuerInformation>

<TimeIssued> and <TimeExpires> contain the time of the issuing operation and the card expiration date, respectively. The expiration date should be regarded as a ‘this-metadata-contract-supported-until’ date, and not an account expiration date, which should be handled as account data at the STS.

<TimeIssued>2006-08-07T23:37:42.3533826Z</TimeIssued>
      <TimeExpires>9999-12-31T23:59:59.9999999Z</TimeExpires>

<TokenServiceList> contains a list of <TokenService> elements that are the data for obtaining the STS metadata, contacting it securely and for authenticating incoming requests.

<TokenServiceList>
        <TokenService>
          <EndpointReference >
            <Address />
            <Metadata />
            <Identity />
          <UserCredential />
        </TokenService>
      </TokenServiceList>

<EndpointReference> is a WS-Addressing endpoint reference, which contains again the STS endpoint; the Metadata section contains the address of the WS-MetadataExchange endpoint.

<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
        <Address>http://www.fabrikam.com:3074/sts</Address>
        <Metadata>
          <Metadata xmlns="https://schemas.xmlsoap.org/ws/2004/09/mex"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                 xmlns:wsx="https://schemas.xmlsoap.org/ws/2004/09/mex">
           <wsx:MetadataSection >
               <wsx:MetadataReference>
                 <Address xmlns="http://www.w3.org/2005/08/addressing">
                    https://www.fabrikam.com:4074/sts/mex
                  </Address>
               </wsx:MetadataReference>
           </wsx:MetadataSection>
           </Metadata>
           </Metadata>

<Identity> contains the certificate associated to the STS, typically the same as the one used in the initial signature.

    <Identity xmlns="https://schemas.xmlsoap.org/ws/2006/02/addressingidentity">
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <X509Data>
          <X509Certificate>
            MIIGR…uEd
          </X509Certificate>
        </X509Data>
      </KeyInfo>
    </Identity>
</EndpointReference>

The <UserCredential> element changes depending on the type of authentication:

For Information Cards backed by a personal card, the <PrivatePersonalIdentifier> element is used to store the PPID.

<UserCredential>
            <SelfIssuedCredential>
              <PersonalPrivateIdentifier>
                 eiavryEeugtsZibaD0moDOiIE+106HbYhYIbst73x5A=
               </PersonalPrivateIdentifier> 
            </ SelfIssuedCredential >
          </UserCredential>

For a Certificate backed card, the element <X509V3Credential> is used by managed card; the <KeyIdentifier> element contains the hash of the smartcard’s certificate. The <DisplayCredentialHint> element is the prompt that the user receives before displaying the smartcard.

<UserCredential>
      <X509V3Credential>
          <X509Data xmlns="http://www.w3.org/2000/09/xmldsig#">
              <KeyIdentifier 
              ValueType="http://docs.oasis-open.org/wss/2004/xx/oasis-2004xx-wss-soap-message-security-1.1#ThumbprintSHA1" 
              xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> 
                     3ce25c9ef8b2d5d99a227e1ea1a28d7f001a3355
              </KeyIdentifier> 
         </ X509Data >
    </X509V3Credential>
</UserCredential>

The <UsernamePasswordCredential> holds the default user name for the card for Username/Password backed cards.

<UserCredential>
    <DisplayCredentialHint>
        Enter your username and password
    </DisplayCredentialHint>
    <UsernamePasswordCredential>
        <Username>FrankLee</Username>
    </UsernamePasswordCredential>
</UserCredential>

The <SupportedTokenTypeList> contains a list of <TokenType> elements that detail the list of token types the STS supports.

<SupportedTokenTypeList>
    <TokenType xmlns="https://schemas.xmlsoap.org/ws/2005/02/trust">
          urn:oasis:names:tc:SAML:1.0:assertion
    </TokenType>
</SupportedTokenTypeList>

The <SupportedClaimTypeList> contains the list of claims that are supported by the card. Single claims are described by the <SupportedClaimType> element, whose elements are self-explanatory (DisplayTag and Description). The example uses predefined claim URIs available in the self-issued set as well as custom claim URIs, such as https://www.contoso.com/myuritest.

<SupportedClaimTypeList>
    <SupportedClaimType
uri="https://schemas.microsoft.com/ws/2005/05/identity/claims/givenname">
        <DisplayTag>Given Name</DisplayTag>
        <Description>Given Name</Description>
    </SupportedClaimType>
    <SupportedClaimType 
Uri="https://schemas.microsoft.com/ws/2005/05/identity/claims/surname">
          <DisplayTag>Last Name</DisplayTag>
          <Description>Last Name</Description>
        </SupportedClaimType>
    <SupportedClaimType Uri="https://schemas.microsoft.com/ws/2005/05/identity/claims/emailaddress">
         <DisplayTag>Email Address</DisplayTag>
         <Description>Email Address</Description>
    </SupportedClaimType>
    <SupportedClaimType Uri=" https://www.contoso.com/myuritest">
          <DisplayTag>My Super Claim</DisplayTag>
          <Description>A claim for all to see</Description>
    </SupportedClaimType>
</SupportedClaimTypeList>

The privacy policy URL is found in the <PrivacyNotice> element:

<PrivacyNotice>
        http://www.fabrikam.com/PrivacyPolicy.xml
</PrivacyNotice>

Custom Faults

When there is a failure involving a user's managed card authentication credential, identity providers (beginning with .NET Framework 3.5) may throw a standard SOAP fault containing a reason for the error. The CardSpace Information Card Selector will display the fault's reason field in a multi-line edit control in its authentication window. Users may, for example, be directed to steps for troubleshooting or receiving support.