Export (0) Print
Expand All

Creating Managed Cards

Download sample

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.

    NoteNote:

    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
NoteNote:

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=http://schemas.microsoft.com/ws/2005/05/identity/claims/givenname
2=http://schemas.microsoft.com/ws/2005/05/identity/claims/surname   3=http://schemas.microsoft.com/ws/2005/05/identity/claims/emailaddress
4=http://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

[http://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="http://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="http://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="http://schemas.xmlsoap.org/ws/2004/09/mex">
           <wsx:MetadataSection xmlns="">
               <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="http://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="http://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 http://www.contoso.com/myuritest.

<SupportedClaimTypeList>
    <SupportedClaimType
uri="http://schemas.microsoft.com/ws/2005/05/identity/claims/givenname">
        <DisplayTag>Given Name</DisplayTag>
        <Description>Given Name</Description>
    </SupportedClaimType>
    <SupportedClaimType 
Uri="http://schemas.microsoft.com/ws/2005/05/identity/claims/surname">
          <DisplayTag>Last Name</DisplayTag>
          <Description>Last Name</Description>
        </SupportedClaimType>
    <SupportedClaimType Uri="http://schemas.microsoft.com/ws/2005/05/identity/claims/emailaddress">
         <DisplayTag>Email Address</DisplayTag>
         <Description>Email Address</Description>
    </SupportedClaimType>
    <SupportedClaimType Uri=" http://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.

NoteNote:

CardSpace cannot guarantee that the fault's message will be non-sensitive; therefore, the message will not be logged to the client's event log.

Glossary

  • Managed Card - An information card issued by an Identity Provider. The information card contains metadata about the Security Token Server and the claims the Identity Provider supports.

  • Identity Provider - The identity provider issues digital identities to users, which contain claims of data about the user.

  • Security Token Service (STS) - The Security Token Service exchanges one token for another. The STS grants a token with claims based on the users’ authentication with the server. Essentially, the server that hands out digital identity information to the user.

See Also

Footer image


© 2007 Microsoft Corporation. All rights reserved.

Community Additions

ADD
Show:
© 2014 Microsoft