Information Card Authentication Schemes

The Information Card Authentication Scheme (ICAS) feature lets you create multiple information card authentication schemes. Each one is configured as a custom authentication scheme.
sm1252sp1
The Information Card Authentication Scheme (ICAS) feature lets you create multiple information card authentication schemes. Each one is configured as a custom authentication scheme.
Information cards are like the physical cards that we carry in our wallets. Each information card represents a set of identity information. For example, an information card that represents a driver's license can contain the following sensitive identity information: photo, birth date, first and last name, and license number. Information cards let users manage their identity information. Users can view their information cards and the associated identity information. They can choose from the available cards for a given information exchange. And they can authorize the release of the identity information that is associated with a selected card.
An Identity Selector is an application that exposes information cards.
2
Introduction to Identity Selectors
An Identity Selector is an application that lets users manage their identity information and their online relationships with Relying Parties and Identity Providers. A Relying Party (RP) is the web site, application, or service that requires identity information to authenticate the user. The Identity Provider (IdP) is a third party that authenticates identity information and creates security tokens that the user can share with the Relying Party.
Identity Selectors allow users to access web-based resources without having to manage a multitude of user names and passwords. Likewise, businesses no longer have to maintain a database of user identity information that can be inaccurate and vulnerable to misuse. Eliminating the maintenance of users and databases reduces risk and liability while enhancing agility.
Identity Selectors also give the user control over the identity information is released to each Relying Party. And finally, Identity Selectors provide users with a consistent user interface and better user experience.
Windows CardSpace
Windows CardSpace is the Microsoft implementation of an Identity Selector. CardSpace provides users with a consistent user interface for interacting with any Relying Party or Identity Provider. The Policy Server supports Windows CardSpace through a custom authentication scheme called Information Card Authentication Scheme (ICAS).
CA Single Sign-On
Information Card Authentication Scheme (ICAS)
The Information Card Authentication Scheme (ICAS) available on the Policy Server supports Windows CardSpace. Each instance of ICAS is configured as a custom authentication scheme in the Administrative UI and implemented like any other custom authentication scheme.
ICAS Overview
Authenticating a user with ICAS involves these components and steps:
  • User
  • Identity Selector
  • Web Agent
  • Relying Party (RP)
  • Identity Provider (IdP)
ICAS overview
ICAS overview
  1. A user wants to visit a protected web site or Relying Party (RP).
  2. The Web agent intercepts the user's request and invokes ICAS.
  3. ICAS sends the RP policy requirements to the Web agent.
  4. The Web agent instructs the browser to launch an Identity Selector on the user's computer and sends the RP policy requirements.
  5. The Identity Selector reads the policy requirements and highlights for the user those information cards that satisfy the requirements. The user selects one highlighted card. The Identity Selector collects the user's credentials and sends them to the Identity Provider (IdP) for authentication. The Identity Selector also sends the RP policy requirements to the IdP and requests a token.
    The user can select a card that contains optional claims that are not required by the RP.
  6. The IdP authenticates the user and processes the policy requirements. It generates a token containing the required claims and sends it back to the Identity Selector.
  7. The Identity Selector displays the claims, and the user approves release of the claims to the RP.
  8. ICAS decrypts the token, verifies the token authenticity and integrity, and associates the user claims to a user's identity in the user database. The Policy Server then performs standard policy-based authorization and grants access to the user if authorized.
  9. The user accesses the web site.
ICAS Terms
The following terms are useful for understanding ICAS:
  • Identity Metasystem
    An architecture that specifies how identity information is shared by users, Relying Parties, and Identity Providers.
  • User
    The person whose identity information is being shared. Sometimes, the user is called the subject.
  • Relying Party (RP)
    The Web site that requests and consumes identity information.
  • Identity Provider (IdP)
    A third party that authenticates identity information and shares the information with Relying Parties by creating security tokens. Credit card companies, banks, government agencies, employers, and insurance companies are all examples of Identity Providers.
  • Security Token Service (STS)
    The technology that the Identity Providers use to create security tokens. A Security Token Service:
    • Authenticates users.
    • Creates security tokens that
      • Contain different subsets of identity information, depending on the requirements of the Relying Party and the restrictions of the user.
      • Are of different types.
        Note:
        SAML 1.0 and 1.1 specifications are supported.
      • Are encrypted for security and signed for authenticity and integrity.
  • Security Token
    A cryptographically signed and encrypted set of claims.
  • Claim
    An assertion of truth. Each token contains one or more claims about the user's identity. Examples of claims are the first name, last name, email address, birth date, and so on. The user or a third-party Identity Provider can make claims.
  • Information Card
    A set of identity information. Information cards are comparable to the physical cards that we carry in our wallets. For example, an information card that corresponds to a driver's license can contain the following sensitive identity information: photo, birth date, first and last name, license number, state, height, and sex.
  • Personal Card
    An information card that contains claims that the user asserts about himself, but a third party does not corroborate the claims. A personal card contains a Private Personal Identifier (PPID) that is generated when the card is created. Personal cards are appropriate for low-sensitivity identity information, such as an email address.
    Personal cards are also called self-issued cards.
  • Managed Card
    An information card contains claims that the user asserts about himself and that are corroborated by a third party. A managed card contains a Private Personal Identifier (PPID) that is generated when the card is created and a pointer to the Identity Provider's STS. Managed cards are appropriate for sensitive identity information, such as a credit card number.
  • Identity Selector
    An application that lets users manage their relationships with Relying Parties and Identity Providers and control how their identity information is shared and used. An identity selector:
    • Enables sharing of information between parties that use multiple communication protocols and security technologies
    • Provides a consistent user interface across multiple Identity Providers and Relying Parties using information cards
    • Highlights those information cards that are available for each exchange of identity information
    • Lets users view and consent to sharing identity information
  • Windows CardSpace
    Microsoft's Identity Selector for the Windows operating system.
  • Information Card Authentication Scheme (ICAS)
    Support for Windows Cardspace, Microsoft's Identity Selector, implemented in
    CA Single Sign-On
    as a custom authentication scheme.
  • Private Personal Identifier (PPID)
    Identifier generated by the Identity Selector when an information card is created.
ICAS Files
Two files are required to configure each instance of ICAS: the fcc file and the properties file.
  • filename.fcc
    Specifies the authentication settings that you can customize for each instance of ICAS.
    • InfoCard.fcc
      A sample fcc file that is shipped with the Web Agent kit.
  • filename.properties
    Specifies how an instance of ICAS behaves.
    • InfoCard.properties
      A sample properties file
     
    When configuring an instance of ICAS in the Administrative UI, the administrator specifies the path to the properties file.
ICAS Prerequisites
Before you can implement ICAS, the following conditions must be met:
  • Web Browser Configuration
    Use one of the following web browsers:
    • Internet Explorer 7.0
    • Firefox 2.x with CardSpace plug-in
  • Web Server Configuration
    The Web Server must be configured for SSL communication. This configuration protects the fcc file.
  • Web Agent Configuration
    The InfoCard.fcc file that is shipped with the Web Agent kit must be customized for each instance of ICAS.
  • Java Runtime Environment (JRE) Configuration
    The Java Runtime Environment must be configured to decrypt security tokens that are encrypted with strong encryption algorithms.
  • Policy Server Configuration
    Policy Server configuration includes the following tasks:
    • Configuring an ICAS properties file.
    • Configuring the certificate data store.
    • Configuring a user directory for ICAS.
    • Creating an instance of ICAS.
    • Configuring an active response that retrieves a claim value.
Configure the Java Runtime Environment (JRE) for ICAS
Configure the Java Runtime Environment (JRE) by installing the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy files. These files are needed to decrypt security tokens that are encrypted with strong encryption algorithms.
Back up the default policy files that are shipped with the JRE before installing the new policy files.
Follow these steps:
  1. Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy files from http://www.oracle.com/technetwork/java/index.html.
  2. Install them in the $NETE_JRE_ROOT\lib\security directory.
  3. Add the following line to the $NETE_JRE_ROOT\lib\security\java.security file:
    security.provider.7=com.rsa.jsafe.provider.JsafeJCE
Configure the Policy Server for ICAS
Configuring the Policy Server for ICAS includes the following steps:
  1. Configure an ICAS properties file.
  2. Store claims for later use in active responses.
  3. Configure the certificate data store for ICAS.
  4. Configure a user directory for ICAS.
  5. Create an instance of ICAS.
  6. Configure an active response that retrieves a claim value.
  7. Configure support for ICAM white list.
Configure an ICAS Properties File
An ICAS properties file specifies how an instance of ICAS behaves. When configuring an instance of ICAS in the Administrative UI, the administrator specifies the path to the associated properties file. To configure a new properties file, open a sample properties file with a text editor and edit the contents. Always save and rename the new properties file.
Note:
Multiple instances of ICAS can use the same properties file.
Example:
A properties file named InfoCard.properties contains the following properties and sample values:
  • fcc
    Specifies the location of the Information Card fcc file.
    Example:
    fcc=https://
    web_server_home
    /siteminderagent/forms/InfoCard.fcc
    Note:
    To activate the Identity Selector, specify "https".
  • vppid_attribute
    Specifies the VPPID attribute value. The command UpdateUserStoreWithVPPID requires this attribute to update a user attribute.
    Example:
    vppid_attribute=mail
  • vppid_claim
    Specifies the claim necessary to disambiguate the user.
    Examples:
    vppid_claim=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    vppid_claim=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    vppid_claim=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • alias
    Specifies the key in the certificate data store that is used to retrieve the SSL certificate of the Relying Party.
    Example:
    alias=rpssl
  • guestuser
    If ICAS is configured in
    anonymous
    mode, this setting specifies the guest user login.
    Example:
    guestuser=guest
  • tokenPrim
    Specifies the provider of the tokenPrim interface.
    Example:
    tokenPrim=com.ca.sm.authscheme.infocard.higgins.TokenAdapter
  • storeclaims_attribute
    Specifies the user attribute where the claims are stored when the command
    StoreClaimsToUserStore
    is executed.
    Example:
    storeclaims_attribute=description
  • preprocessingchain
    Defines a chain of commands to execute during user disambiguation.
    Example:
    preprocessingchain=+vppidchain
    For more information, see Configure ICAS Command Chains.
  • postprocessingchain
    Defines a chain of commands to execute during user authentication.
    Example:
    postprocessingchain=+vppidchain;com.ca.sm.icas.command.StoreClaimsToContext
    For more information, see Configure ICAS Command Chains.
  • errorprocessingchain
    Defines a chain of commands to execute during error processing.
    For more information, see Configure ICAS Command Chains.
  • whiteListLocation
    (Optional) Defines the location of the XML file that contains the White List that is specified by Federal Identity, Credentialing, and Access Management (ICAM).
    Example:
    whiteListLocation=C:\\Program Files\\ca\\siteminder\\config\\WhiteList.xml
    For more information about ICAM White List, see Configure Support for the ICAM White List.
Configure ICAS Command Chains
Command chains are defined in the ICAS properties file. A chain is a set of commands that executes in an orderly manner.
The named chain commands include:
  • preprocessing
  • postprocessing
  • errorprocessing
These named chains are present by default.
Consider the following information:
  • If the specific named chains are found in the ICAS properties file, then ICAS uses these named chains.
  • You can define your own chains then place them in the ICAS properties file and refer them in the named chains.
  • If any customized chain is not referred in any of these named command chains, that chain execution is ignored.
According to your requirements, configure the following class files:
5
5
Key Class Files to Configure ICAS
The following key class files are used to configure ICAS:
  • com.ca.sm.icas.StoreClaimsToSessionStore
    Stores extracted claims to the session store of Policy Server.
  • com.ca.sm.icas.command.ExecuteClaimChain
    Executes a set of commands over a claim. For each claim name, which forms the last part of the namespace, ICAS looks for a chain that is defined as chainID.claimID in the properties file. If the chain definition is found, then ICAS executes it and passes the context with the specific claim.
    Example:
    For executeClaimCommand1=com.ca.sm.icas.command.ExecuteClaimChain, define the email claim as follows:
    • executeClaimCommand1.emailaddress=com.ca.sm.icas.command.DumpClaimsCommand;
      Processes the DumpClaimsCommand if a token is found with an emailaddress claim.
  • com.ca.sm.icas.command.HashVPPID
    Generates a hash of the VPPID claim attribute.
  • com.ca.sm.icas.command.SetVPPIDAsAnonymous
    Sets the VPPID claim attribute value to anonymous. This class file is used for logging in with information cards that are not linked to any user accounts (anonymous access).
  • com.ca.sm.icas.command.SetVPPIDFromToken
    Sets the VPPID claim attribute value from the information card token to the context object.
  • com.ca.sm.icas.command.StopChain
    Returns the value true, which stops the execution of the currently running chain.
  • com.ca.sm.icas.command.StoreClaimsToContext
    Reads the claims from the information card token and store them to the application-specific context.
  • com.ca.sm.icas.command.StoreClaimsToUserStore
    Stores the claims read from the information card token to a specified user attribute (in the ICAS properties file) in the user directory.
  • com.ca.sm.icas.command.TransformScriptInClaim
    Escapes the script tags (<, >) in the claims using HTML entities. For example, <td> becomes &lt;td;&gt.
  • com.ca.sm.icas.command.TransformSqlInClaim
    Escapes the characters in a claim value so that it can be passed to an SQL query.
  • com.ca.sm.icas.command.TranslateErrorCode
    Translates the exception string that is found within context. This translated string is stored back into the context.userText that is available in the FCC.
  • com.ca.sm.icas.command.TranslateErrorCodeFromParms
    Translates the exception string that is found within the ICAS properties file. This translated string is stored back into the context.userText that is available in the FCC.
  • com.ca.sm.icas.command.UpdateUserStoreWithVPPID
    Stores the claims read from the information card token to a specified user attribute (available in the ICAS properties file) from the user directory.
Class Files to Check the Values of Claims
The following class files are used to check the values of claims:
  • com.ca.sm.icas.StoreClaimsToSessionStore
    Stores extracted claims to the session store of Policy Server.
  • com.ca.sm.icas.command.ErrorIfEmptyClaim
    Generates an exception when the claim is empty.
  • com.ca.sm.icas.command.ErrorIfMultiValueClaim
    Generates an exception when the given claim has multiple values.
  • com.ca.sm.icas.command.ErrorIfNotEmptyClaim
    Generates an exception when the given claim is not empty.
  • com.ca.sm.icas.command.ErrorIfNotMultiValueClaim
    Generates an exception when the given claim is not multivalued.
  • com.ca.sm.icas.command.ErrorIfNotNullClaim
    Generates an exception when the given claim is not null.
  • com.ca.sm.icas.command.ErrorIfNotSingleValueClaim
    Generates an exception when the given claim is not single valued.
  • com.ca.sm.icas.command.ErrorIfNullClaim
    Generates an exception when the given claim is null.
  • com.ca.sm.icas.command.ErrorIfSingleValueClaim
    Generates an exception when the given claim is single valued.
Class Files to Debug
The following class files are used for debugging purpose:
  • com.ca.sm.icas.command.debug.DumpChainID
    Displays the chain ID on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.DumpClaim
    Displays the VPPID claim details (name and value) on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.DumpClaims
    Displays the details of all the claims in the token on the console
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.DumpContext
    Displays the details of the context object on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.DumpParameters
    Displays the details of the parameters that are specified in the ICAS properties file on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.DumpSystemVars
    Displays the details of the system environment on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.DumpThreadStack
    Displays the stack trace of the executing thread on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.GenerateClaim_claims_AsHTML
    Generates a new claim "_claims_" that has an HTML table representing the known claims. You can use this claim in an active response to create a cookie or header to show the retrieved claims to a user.
  • com.ca.sm.icas.command.debug.GenerateClaim_parameters_AsHTML
    Generates an HTML table representing the parameters that are specified in the ICAS properties file. You can use this HTML table in an active response to create a cookie or a header to show the retrieved claims to a user.
  • com.ca.sm.icas.command.debug.LogClaim
    Writes the claim details (name and value) in the chain context to the Policy Server trace logs.
  • com.ca.sm.icas.command.debug.LogClaims
    Writes the details of all the claims in the token to the Policy Server trace log.
  • com.ca.sm.icas.command.debug.LogDecryptedClaims
    Logs the decrypted XML token to the Policy Server trace log.
  • com.ca.sm.icas.command.debug.LogEncryptedClaims
    Logs the encrypted token that is obtained from the IDP to the Policy Server trace logs.
  • com.ca.sm.icas.command.debug.START
    Displays a START message on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.STOP
    Displays a STOP message on the console.
    To view the output, start the Policy Server in the console mode.
  • com.ca.sm.icas.command.debug.ThrowException
    Generates an exception object that includes the claim value as a part of the message.
Store Claims for Later Use in Active Responses
You can store claims for later use in active responses. To store claims for later use, add the following property to the properties file:
  • postprocessingchain
    Defines the chain of commands to execute during user authentication. This phase includes any claim transformation and storage commands.
    Example:
    postprocessingchain=com.ca.sm.authscheme.infocard.command.StoreClaimsToContext
Configure the Certificate Data Store for ICAS
Consider the following information:
  • The Relying Party must use SSL to protect the fcc file.
  • The Relying Party must export the SSL certificate that is associated with the website to a pfx file.
  • A Policy Server administrator configures the certificate data store for ICAS by importing the SSL certificate from the Relying Party website.
  • The imported certificate is associated with an alias, which is stored in the fcc file. The private key of the certificate is used to decrypt the security token and verify the digital signature.
Follow these steps:
  1. Use the Web Server Certificate Wizard and export the SSL certificate from an IIS web server to a pfx file.
    For more information, see the Microsoft documentation. To import the SSL certificate from the pfx file, the Policy Server uses the password that you provide when exporting the SSL certificate to the pfx file.
  2. Import the SSL certificate into the certificate data store using the Administrative UI.
Configure a User Directory for ICAS
Authentication of the user depends on finding a match between one of the claims that are presented to ICAS and a user attribute in the user database. During token disassembly, the specified claim value is used as a lookup value in the user directory. Therefore, configure the user directory so that the LDAP lookup string or SQL query scheme specifies the user attribute that corresponds to the specified claim.
The following examples show how to configure an LDAP lookup string and SQL query scheme for an email address.
  • LDAP Example
    LDAP User DN Lookup
    • Start
      (mail=
    • End
      )
  • SQL Example
    SQL Queries
    • Get User/Group Info
      SELECT EmailAddress, 'User' FROM SmUser WHERE EmailAddress = '%s' UNION SELECT Name, 'Group' FROM SmGroup WHERE Name = '%s'
    • Authenticate User
      SELECT EmailAddress FROM SmUser WHERE EmailAddress = '%s' AND Password = '%s'
Create an Instance of ICAS
You can create an instance of ICAS by specifying a custom authentication scheme in the Administrative UI.
Limit:
Each policy store can support up to ten instances of ICAS.
Follow these steps:
  1. Click Infrastructure, Authentication.
  2. Click Authentication Schemes.
  3. Click Create Authentication Scheme.
  4. Select Create a new object of type Authentication Scheme, and click OK.
  5. Enter the authentication scheme name and description.
  6. Select Custom Template from the list of Authentication Scheme Types.
    The Scheme Setup group fields appear.
  7. Enter a value in the Protection Level field.
  8. Clear the Password Policies enabled for this Authentication Scheme Types.
    Note:
    ICAS does not support Password Policies.
  9. Enter the values for the following fields in Scheme Setup:
    • Library
      smjavaapi
      Note:
      The custom authentication scheme uses the Java Authentication API.
    • Secret and Confirm Secret
      Leave these fields blank.
      Note:
      The custom authentication scheme does not use the shared secret.
    • Parameter
    Type the following two parameters in the Parameter field and separate them by a space:
    • com.ca.sm.icas.SmAuthInfoCard
      This is the fully qualified name of the class that implements the SmAuthScheme interface.
    • policy_server_home\config\icas\InfoCard.properties
      This is the location of the properties file.
    • Example:
      com.ca.sm.icas.SmAuthInfoCard
      policy_server_home
      \config\icas\InfoCard.properties
  10. (Optional) Select the Store Auth Scheme Context to Session Store option in the Scheme Setup. This option specifies that the authentication context data is persisted.
  11. Click Submit.
    The Create Authentication Scheme task is submitted for processing.
Configure an Active Response that Retrieves a Claim Value
To configure an active response that retrieves a claim value after authentication is complete, use the custom class com.ca.sm.icas.GetClaimValue
Storing and retrieving claim values requires a session store.
Follow these steps:
  1. Click Policies, Domain.
  2. Click Responses.
  3. Click Create Response.
  4. Select a domain, and click Next.
  5. Type the name and a description of the response.
  6. Specify Web Agent as the Agent Type.
  7. Click Create Response Attribute in Attribute List.
  8. Select WebAgent-HTTP-Header-Variable or WebAgent-HTTP-Cookie-Variable from the list of attributes in Attribute Type.
  9. Select Active Response as the Attribute Kind in Attribute Setup.
  10. Type the following values in the Attribute Fields.
    • Cookie or Variable Name
      Specifies the name of the claim.
      Example:
      emailaddress
    • Library Name
      Specifies the name of the library.
      Value:
      smjavaapi
    • Function Name
      Specifies the name of the function.
      Value:
      JavaActiveExpression
    • Parameters
      Specifies the custom ICAS command and the location of the file, claims.xsd, that defines standard claim types according to the Information Card model.
      Example:
      com.ca.sm.authscheme.infocard.GetClaimValue http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  11. Click OK.
    The response that retrieves a claim value is created.
Configure Support for the ICAM White List
The ICAS implementation supports the Federal Identity, Credentialing, and Access Management Identity Metasystem Interoperability 1.0 Profile (ICAM IMI 1.0 Profile) specification, which is based on White List of issuers and LOA authorization.
For more information about White List and LOA support, see
ICAM IMI 1.0 Profile Release Candidate
.
To enable White List processing, update the following parameters in the
Infocard.properties
file.
  • postprocessingchain
    Defines the chain of commands to execute during user authentication.
    Example:
    postprocessingchain=com.ca.sm.icas.whiteListChecker.whiteListChecker
  • whitelistlocation
    Defines the location of the XML file that contains the White List that is specified by ICAM.
    Example:
    whitelistlocation=C:\\Program Files\\ca\\siteminder\\config\\WhiteList.xml
The ICAS implementation supports the verification of three Level of Assurances (LOAs)
  • LOA1
  • LOA2
  • LOA3
White List processing is mandatory to verify LOA1, LOA2, and LOA3. Append the following details to the postprocessingchain parameter to support LOA processing:
  • For LOA1 processing
    postprocessingchain=com.ca.sm.icas.whiteListChecker.whiteListChecker; com.ca.sm.icas.whiteListChecker.ErrorIfLOA1ClaimMissing
  • For LOA2 processing
    postprocessingchain=com.ca.sm.icas.whiteListChecker.whiteListChecker; com.ca.sm.icas.whiteListChecker.ErrorIfLOA2ClaimMissing
  • For LOA3 processing
    postprocessingchain=com.ca.sm.icas.whiteListChecker.whiteListChecker; com.ca.sm.icas.whiteListChecker.ErrorIfLOA3ClaimMissing