Summary

This document will guide you through the steps to provide Single-Sign-On to CA SSO (formerly CA SiteMinder) using the CA Agent API with PhenixID Authentication Services.

Overview

There are two ways for an application to use PhenixID Authentication Services to perform user authentication and CA SSO integration:

1. Web browser authentication.
   In this scenario, the application will redirect the end user client web browser to PhenixID Authentication Services. PhenixID Authentication Services will perform user authentication and, when done, it will call out to CA SSO to retrieve CA SSO sso token. The value of the sso token will be written to a cookie. PAS will then redirect the end user client web browser to specified target destination.
2. API authentication.
   In this scenario, the application will consume the PhenixID Authentication Services REST API. This means the end user client will have no direct interaction with PhenixID Authentication Services. The PhenixID REST API function will perform authentication and, when done, it will call out to CA SSO to retrieve CA SSO sso token. The sso token value will be returned to the application (on the api response).

System Requirements

• PhenixID Authentication Services 3.0 or higher
• Download PAS-CA-SSO-integration.zip from this location. Only for PAS 4.x and lower.
• CA Single Sign-On SDK installed on the same server as PhenixID Authentication Services
• CA Single Sign-On SDK Agent API configured (config/SmHost.conf) to communicate with CA SSO Policy Server. Please view Appendix 1 for an example of SmHost.conf.
• For web browser authentication:
  CA Single Sign-On Policy Server configured to redirect non-authenticated requests to https://<pas_server_domain>:<pas_port>/sm/authenticate/sm

Instruction

1. Install PhenixID Java AuthScheme on CA policy server

1. Unzip PAS-CA-SSO-integration.zip. Only for PAS 4.x and lower.
2. Follow the instructions in the document Installation of PhenixID Java AuthScheme for CA Single-Sign On.doc

2. Configure PhenixID Authentication Services

2.1 Common configuration

1. Copy these files from the CA SSO SDK installation on the same machine:
   cryptoj.jar
   smagent.jar
   smanalyzer.jar
   smjavaagentapi.jar
   SmJavaApi.jar
   smjavasdk2.jar
2. Place the copied files in <phenixid_server_root>/lib/

2.2 Configuration – Web browser authentication

1. Only for PAS 4.x and lower: copy phenix-siteminder-auth-2.1.jar and ca_base-1.0-SNAPSHOT.jar from the unzipped folder to <phenixid_server_root>/mods/com.phenixidentity~auth-http~<version>/lib/
2. Restart PhenixID Authentication Services.
3. Logon to configuration manager
4. Click Advanced
5. Click on the pen to the right of Authentication – HTTP
6. Add an authenticator to be used. This will vary based on your requirements. Information about available http authenticators and how to use them can be found here. In this scenario, you must use an authenticator targeted for PhenixID web apps authentication.In your authenticator config, make sure the alias is set to sm and successURL is set to /sm/authenticate/SiteMinderAuthThis is an example of a simple username-password authenticator. The parameter includeQueryString=true must be part of the configuration – to make sure the query string parameters passed by the initial redirect from CA SSO are passed through the flow.{
   “alias”: “sm”,
   “name”: “PostUidAndPassword”,
   “configuration”: {
   “pipeID”: “374b4120-15bd-4ce5-b53f-4ea13df5c1b7”,
   “successURL”: “/sm/authenticate/SiteMinderAuth”,
   “includeQueryString”: “true”,
   “translationKey”: “login.messages.information.body.enduser”,
   “headingtranslationKey”: “login.messages.information.header.enduser”,
   “title”: “login.messages.information.title.enduser”,
   “allowLanguageChange”: “true”
   },
   “created”: “2017-03-29T08:15:46.949Z”,
   “id”: “a4b6dd5f-e5cb-48f8-bc2a-bc413b489651”
   }
7. Add an additional authenticator for the Siteminder integration, SiteMinderAuth.Change the sm_phenixid_cfg_path to make sure it points to the correct file path.
   Change the agent_client_name value. This must match the value of hostname in the SmHost.conf file.
   The SMSession cookie holds the encrypted value for the Siteminder session. The values for the cookie (path and domain) must be configured using the cookie_domains configuration parameter. Multiple cookie domains are supported.
   By default, the userID of the authenticated session will be used as identifier against CA SSO. Use optional config parameter userid_session_attribute to use another session attribute as identifier against CA SSO.
   Change the allowed_redirect_pattern regex value to only allow specific redirect target URLs.
   Example authenticator for SiteMinder.

   {
   “alias”: “SiteMinderAuth”,
   “name”: “SiteMinderAuth”,
   “configuration”: {
   “sm_phenixid_cfg_path”: “/opt/ca/sdk/config/SmHost.conf”,
   “unauthenticated_url”: “/sm/authenticate/sm”,
   “agent_client_name”: “pas1”,
   “idle_timeout”: “0”,
   “session_timeout”: “0”,
   “protected_resource”: “/login”,
   “allowed_redirect_pattern“: “.*\\.example.org.*”,
   “destroy_session”: “true”,
   “error_redirect_target”: “http://example.org/displayError.html”,
   “cookie_domains”: [
   {
   “name”: “SMSESSION”,
   “path”: “/”,
   “secureOnly”: “true”,
   “domain”: “example.org”
   }
   ],
   “userid_session_attribute”: “carLicense”
   },
   “id”: “SiteMinderAuth”
   }

8. Click Save

2.3 Configuration – API Authentication

1. Copy phenix-siteminder-valves-1.0.jar and ca_base-1.0-SNAPSHOT.jar from the unzipped folder to <phenixid_server_root>/mods/com.phenixidentity~phenix-pipes~<version>/lib/
2. Restart PhenixID Authentication Services.
3. Logon to configuration manager
4. Click Advanced
5. Click on the pen to the right of Pipes
6. Add the SiteMinderAuth valve to the API pipe used. The valve is working on an item so an item must exist in the flow when the valve executes.Change parameters below to match your environment.

   {
   “name”: “SiteMinderAuthValve”,
   “config”: {
   “protected_resource”: “/login”,
   “userID”: “{{item.sAMAccountName}}”,
   “targetProperty”: “SMSESSION”,
   “agent_client_name”: “pas”,
   “failover”: “true”,
   “sm_phenixid_cfg_path”: “/opt/siteminder/sdk/config/SmHost.conf”,
   “idle_time_out”: “60”,
   “session_time_out”: “60”
   }
   }

7. Click Save

Test

Web browser authentication

1. Open a web browser
2. Browse to the resource that is protected by CA SSO
3. You should be redirected to PhenixID Authentication Services and prompted for authentication.
4. Authenticate
5. You should be redirected back to the resource protected by CA SSO
6. You can now access the resource.

API authentication

1. Open the application / api consumer
2. Trigger API request to PhenixID Authentication Services (mapping to the pipe containing the SiteMinderAuthValve)
3. Verify that the property “sm_sso_token” is part of the API response

Troubleshooting

• Check PhenixID Authentication Services log (server.log)
• Check your CA Single-Sign On logs
• Use web browser developer tools to make sure the SMSession cookie is set

Notes

When the Siteminder authenticator is initiated the first time, it will create a file named AgentGUID.conf in the phenixid server root directory. This is normal CA SSO Agent API behavior.

Appendix

Appendix 1

This is an example of SmHost.conf.

Host Registration File - /opt/ca/sdk/config/SmHost.conf
#
# This file contains bootstrap information required by
# the SiteMinder Agent API to connect to Policy Servers
# at startup. Be sure the IP addresses and ports below
# identify valid listening Policy Servers. Please do not
# hand edit the encrypted SharedSecret entry.

hostname="pas1"
hostconfigobject="AIntranetSettings"
policyserver="policyserver1.example.org,44441,44442,44443"
policyserver="policyserver2.example.org,44441,44442,44443"
requesttimeout="60"
sharedsecret="{RC2}xxxxxxx"
sharedsecrettime="1392676735"
fipsmode="COMPAT"