Policy Server Guides › Policy Server Configuration Guide › Authentication Schemes › OpenID Authentication Scheme

OpenID Authentication Scheme

This scenario describes how a CA SiteMinder® administrator and a CA SiteMinder® agent owner configure an OpenID authentication scheme.

The CA SiteMinder® OpenID authentication scheme lets CA SiteMinder® users submit credentials through an OpenID provider. The OpenID provider authenticates the user and sends CA SiteMinder® an authentication response. The Policy Server verifies the authentication response, completes the authentication process, and authorizes access to the resource.

The goal of the scenario is to let the intended audience:

• Identify how the OpenID authentication process works.
• Configure the required agent–side components to enable the authentication scheme.
• Configure the required Policy Server–side components to enable the authentication scheme.

CA SiteMinder® 12.52 supports OpenID versions 1.1 and 2.0 and OpenID Attribute Exchange version 1.0.

How OpenID Authentication Works in CA SiteMinder®

The following process explains how OpenID authentication works in CA SiteMinder®:

1. A user requests the resource.
2. The agent intercepts the request and contacts the Policy Server to see if the resource is protected.
3. The Policy Server determines that the resource is protected with an OpenID authentication scheme and requests that the agent redirect the user to the OpenID forms credential collector (FCC).
4. The agent redirects the user to the FCC.
5. The user completes one of the following tasks. How the FCC is customized determines the work flow in this step. The user can:
   • Select an OpenID provider and submit OpenID credentials at the provider site.
   • Select an OpenID provider and submit an OpenID user name.
   • Select OpenID and submit the complete OpenID user identifier.
6. The FCC constructs the OpenID user identifier and passes it to the Policy Server.
7. The Policy Server redirects the user to the OpenID provider for authentication by constructing an OpenID authentication request.
8. The user authenticates with the OpenID provider using provider–specific credentials.
9. The OpenID provider redirects the successful authentication response to the FCC.
10. The agent passes the authentication response to the Policy Server.
11. The Policy Server verifies the provider authentication response and uses it to determine the value of the first required claim. The Policy Server searches all user directories in the policy domain to locate a user with an attribute that matches the claim value. Upon a match, the Policy Server authenticates the user.

    Note: The authentication scheme supports an anonymous mode of authentication. In anonymous mode, the Policy Server does not use the claim value to map to a CA SiteMinder® user. The Policy Server searches all user directories in the policy domain for a user matching the anonymous user that you defined in the authentication scheme.

12. The Policy Server returns the session details of the authenticated user to the FCC.
13. The FCC creates the CA SiteMinder® session cookie and passes it to the Web browser. The user is redirected to the requested resource and the Policy Server maintains all authorization decisions.

How to Configure an OpenID Authentication Scheme

This section describes how a CA SiteMinder® administrator can configure the OpenID authentication scheme. The following diagram illustrates the required tasks:

Follow these steps:

1. Enable the web agent OpenID plug–in.
2. Customize the OpenID forms credential collector.
3. Modify the OpenID providers configuration file.
4. Modify the agent configuration object.
5. Disable the FCCCompatMode parameter.
6. Configure the OpenID authentication scheme.

Enable the Web Agent OpenID Plug–in

The OpenID plug–in is referenced in the web agent configuration file (WebAgent.conf). The plug–in is required to let agents communicate with an OpenID provider and communicate the OpenID provider authentication response to the Policy Server.

Contact agent owners and instruct them to enable the required plug–in.

Follow these steps:

1. Log in to the web agent host system.
2. Open the web agent configuration file.

   Note: The default location of the file depends on the web server type:

   • IIS

     agent_home\bin\IIS
     

     agent_home

     Specifies the agent installation path.

   • Oracle iPlanet (iPlanet/SunOne)

     web_server_home/https-hostname/config
     

     web_server_home

     Specifies the web server installation path.

   • Apache, IBM HTTP Server, and Oracle HTTP Server

     web_server_home/conf

     web_server_home

     Specifies the web server installation path.

   • (Windows) Domino

     C:\lotus\domino
     

   • (UNIX) Domino

     $HOME/notesdata
     

3. Uncomment line that loads the OpenID plug–in.

   Example:

   #LoadPlugin="C:\Program Files\CA\webagent\bin\OpenIDPlugin.dll"
   

4. Save the file.
5. Restart the web server.

Customize the OpenID Forms Credential Collector

A sample OpenID FCC is included with the web agent installation. The FCC is required to let users authenticate by:

• Entering an OpenID provider user name.
• Entering a complete OpenID identifier.

By default, the FCC presents numerous OpenID providers. Contact the agent owner and instruct them to display only those providers that the protected application supports by modifying the FCC.

Follow these steps:

1. Log in to the web agent host system.
2. Go to the following location:

   agent_home\samples\forms
   

   agent_home

   Specifies the web agent installation path.

3. Open the following file with a text editor:

   openid.fcc
   

4. Review the FCC. Determine if the OpenID providers you require are available or if you have to add a profile. The default providers are located in the following sections:

   var providers_large
   var providers_small
   

5. Remove the unnecessary providers from the FCC by commenting them. Begin the comment at the provider name. End the comment at the end of the profile.

   Example:

   /*google : {
   

   name : 'Google',
   url : 'https://www.google.com/accounts/o8/id'
   

   },*/
   

6. If you have to add a provider, locate the custom provider ID in either the large or small provider sections:

   Example:

   }/*,
   myprovider : {
   

   name : 'MyProvider',
   label : 'Enter your provider username',
   url : 'http://ca.com/{username}/',
   image : 'images/image.png'
   

   }*/
   

   Note: The separate provider sections correspond to the sizes of provider icons that the FCC displays:

   • The supported size of an icon in the large section is 100 pixels by 60 pixels. The FCC can display up to five large icons.
   • The supported size of an icon in the small section is 24 pixels by 24 pixels. The FCC can display up to 11 small icons.
   1. Add the new provider by removing the following characters:

      /*
      */
      

   2. Update the label and name values. The label value determines the text that the user sees after clicking the provider icon.

      Example:

      myprovider : {
      name : 'Foward Inc',
      label : 'Enter your Forward Inc user name',
      url : 'http://ca.com/{username}/',
      image : 'images/image.png'
      }
      

      Note: Forward, Inc. is a fictitious company name that is used strictly for instructional purposes only and is not meant to reference an existing company.

   3. Update the URL value. The URL value represents the OpenID user identifier. The Policy Server forwards the user identifier to the OpenID provider.

      Example:

      myprovider : {
      name : 'Foward Inc',
      label : 'Enter your Forward Inc user name',
      url : 'http://{username}.forwardinc.com/'
      image : 'images/image.png'
      }
      

   4. Update the image value. The image value represents the location of the provider icon that the FCC is to display.

      Example:

      myprovider : {
      name : 'Foward Inc',
      label : 'Enter your Forward Inc user name',
      url : 'http://{username}.forwardinc.com/'
      image : 'images/forwardinc.png'
      }
      

7. By default, the FCC displays the provider icons in the order in which the provider ID is configured and enabled in the FCC. If you want to change the icon order, adjust the order of the provider IDs accordingly.

   Important! The default provider IDs include the following image index property:

   imageidx
   

   Do not remove or change the property. The property verifies that the FCC displays the correct provider icon.

8. Save the script.
9. Restart the web server.

Modify the OpenID Provider Configuration File

The product provides an OpenID provider configuration file. The file must reference the configuration details of each provider that the protected application supports. If the file does not include the correct settings, authentication fails.

• By default, the file includes sample settings for all of the providers that the OpenID FCC makes available. Review the sample settings and modify them as required.

  Important! The values are samples only. We recommend that you verify all configuration settings with your OpenID provider before deploying the authentication scheme.

• If you added a provider to the FCC, add configuration settings for the provider.

Follow these steps:

1. Log in to the Policy Server host system.
2. Go to the following location:

   siteminder_home\config\properties
   

   siteminder_home

   Specifies the Policy Server installation path.

3. Do one of the following steps:
   • Open the default provider configuration file:

     Openidproviders.xml
     

   • Create another instance by copying the default configuration file. Each OpenID authentication scheme that you configure can use its own provider configuration file.

     Example: You can enable Federal Identity, Credential, and Access Management (ICAM) compliance for one instance of the authentication scheme and can disable ICAM compliance for another.

4. Review the file and determine if the OpenID provider settings you require are available or if you have to add settings.
5. If you have to add settings, complete the following steps:
   1. Copy an existing OpenID provider node and all of its child nodes. All required and optional nodes are included within the following nodes:

      <OpenIDProvider>
      </OpenIDProvider>
      

   2. Add the new OpenID provider node and all of its child nodes to the following root node:

      <TrustedOpenIDProviders>
      </TrustedOpenIDProviders>
      

6. Configure the settings for each provider that the authentication scheme is to support using the following node descriptions:

   OpenIDProvider RequestType="value"

   Indicates the beginning of the configuration settings for a provider.

   RequestType

   (Optional) Specifies the schema type that the provider supports.

   Valid values: ax or sreg.

   Default: ax.

   ProviderName

   Specifies the URL of the OpenID provider hosting the service. The value can include a comma–separated list of provider URLs.

   Required Claims

   Specifies the claims that the OpenID provider returns as part of the authentication request. If the provider cannot provide all of the required claims, authentication fails. This node requires at least one claim node.

   Claim

   Defines an individual required claim.

   URI

   Specifies the URI form of the OpenID provider claim. The Policy Server constructs the authentication request using this value.

   Important! Verify that the value of the first required claim maps to a user attribute in your user directories. The Policy Server determines the value of the first required claim that is based on the provider authentication response. The Policy Server then searches all user directories in the policy domain for a user that matches the claim value. If the Policy Server cannot map the claim value to a user attribute, authentication fails.

   Value: The value must adhere to the type of schema that the provider supports.

   Alias

   (Optional) Defines the user-friendly name of the URI node value and prevents the URI from being stored or referenced. The system uses the alias to identify the claim.

   Value: Any string.

   Example: Instead of storing a URI that returns the first name of users in the session store, the system can reference the claim name as fullname.

   Note: The system appends the following prefix to an alias that is stored in the session store:

   smopenidclaim

   Optional Claims

   (Optional) Specifies the optional claims that the OpenID provider is to return as part of the authentication request. If the provider cannot provide an optional claim, authentication does not fail. This node requires at least one claim node.

   Pape

   (Optional) Defines the properties that ICAM compliance requires. If you are configuring the authentication scheme for ICAM compliance, this node and all child nodes are required.

   max_auth_age

   (Optional) Specifies the time for which the OpenID provider user session is valid. If the user session is valid, the OpenID provider authenticates the user for a protected resource using a provider–specific cookie. If the session expires, the user is prompted to reauthenticate.

   Unit of measurement: seconds.

   Default: 0.

   If you leave the default value, the user must authenticate against the OpenID provider, regardless of a valid session.

   Value: The value must be a positive integer.

   Policies

   (Optional) Specifies a comma–separated list of the ICAM policies to which the OpenID provider must adhere. If the provider does not adhere to the compliance level, authentication fails.

7. Save and close the file.

Modify the Agent Configuration Object

The default settings for the ignore extensions ACO parameter prevent the OpenID FCC from displaying. Modify the default settings using the Administrative UI.

Follow these steps:

1. Click Infrastructure, Agent Configuration Objects.
2. Locate the agent configuration object for the agents that are to redirect the user requests to the FCC.
3. Open the object by clicking the edit icon.
4. Locate the following parameter:

   IgnoreExt
   

5. Click the edit icon and add the following values:
   • .css
   • .js

   Note: Separate the values with a comma.

   Example:

   .class, .gif, .jpg, .jpeg, .png, .fcc, .scc, .sfcc, .ccc, .ntc,.css,.js
   

6. Click OK.
7. Click Submit.

   The agent configuration object is updated with the excluded resource extensions.

Disable the FCCCompatMode Parameter

Agents use an FCCCompatMode configuration parameter for backward compatibility with older versions of the product. For newer versions of the product (such as 12.52), this parameter must be disabled for better security when using certain features.

Note: This procedure assumes you configure your agents centrally, using an agent configuration object on a Policy Server. If you use the local agent configuration method instead, disable the FCCCompatMode parameter in your LocalConfig.conf file.

Follow these steps:

1. From the Administrative UI, click Infrastructure, Agent Configuration Objects.
2. Click the edit icon next to the agent configuration object that you want.
3. Locate the following parameter:

   FCCCompatMode

   Enable an FCC/NTC to serve up forms for resources that 4.x Web Agents protect or third-party applications.

   Note: SMUSRMSG is supported for the custom authentication scheme only when FCCCompatMode set to yes.
   Limits: yes, no

   Default: (traditional agents) Yes

   Default: (framework agents) No

   Important! Setting this parameter to no removes support for version 4.x of the Netscape browser.

4. Verify that the value is set to no. If the value is yes, continue with the following steps:
   1. Click the edit icon to the left of the parameter.

      The Edit parameter dialog appears.

   2. Highlight the Value field, and then type no.
   3. Click OK.

      The Edit parameter dialog closes.

   4. Click Submit.

      The FCCCompatMode parameter is disabled and a confirmation message appears.

Configure the OpenID Authentication Scheme

You use the Administrative UI to configure the OpenID authentication scheme object.

If your network includes multiple cookie domains and each cookie domain requires the authentication scheme, configure a separate authentication scheme object in each cookie domain.

Note: For operation on any Solaris platforms, modify the java.security file in the directory jre_root/lib/security so that the sun.security.provider.Sun provider is registered as the first provider.

Follow these steps:

1. Click Infrastructure, Authentication, Authentication Schemes.
2. Click Create Authentication Scheme.
3. Select the new object option and click OK.

   The Create Authentication Scheme page appears.

4. Enter a name and a protection level.
5. Select the OpenID template from the Authentication Scheme Type list.

   The scheme-specific settings appear.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

6. Configure the remaining parameters and click Submit.

Important! If you change any of the proxy settings or the post processing chain setting, restart the Policy Server.

You have completed the required tasks to configure an OpenID authentication scheme. You can now bind the authentication scheme to a policy realm and an Enterprise Policy Management (EPM) application component.