Creating Managed Cards
A managed card is an information card issued by an Identity Provider. It contains:
Details about the entity that issues the card:
Card Name.
Certificate.
STS (Security Token Service) and MEX (Metadata Exchange) 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/password pair.
.gif)
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 to the Card Writer is found in the CardWriter Folder (in C#).
ManagedCardWriter.cs
The source code to 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.
|
The display name of the card that the user sees. The user can modify the name after it is imported into their Identity Selector. |
|
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. |
|
Each new version of the same card should get an incremented version number. |
|
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.
|
The endpoint URL of the Identity Provider STS. |
|
The MEX endpoint for the STS. In CardSpace, HTTPS is required for the MEX endpoint. |
|
The URL for the location of the privacy policy of the Identity Provider. |
|
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 |
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=http://my-uri.com/test
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://my-uri.com/test]
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 passwordFor 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 passwordFor 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 />
<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>
<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 (such as https://schemas.microsoft.com/ws/2005/05/identity/claims/givenname) as well as custom claim URIs, such as http://my-uri.com/test.
<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="http://my-uri.com/test">
<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>
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
Other Resources
Installing CardSpace Sample Certificates
.gif)
Send comments about this topic to Microsoft.
© Microsoft Corporation. All rights reserved.