CA API Gateway 9.1

9.4 9.1

Authenticate with CA Single Sign-On R12 Protected Resource Assertion

Installing and configuring the CA Single Sign-On R12 Custom Assertion package in the Gateway installs and enables the Authenticate with CA Single Sign-On R12 Protected Resource assertion in the Policy Manager. This assertion instructs the Gateway to delegate the authentication and authorization tasks required to gain access to a protected service on the CA Single Sign-On Policy Server version 12.0 running in FIPS-only mode.
gateway90
Installing and configuring the CA Single Sign-On R12 Custom Assertion package in the Gateway installs and enables the
Authenticate with CA Single Sign-On R12 Protected Resource
assertion in the Policy Manager. This assertion instructs the Gateway to delegate the authentication and authorization tasks required to gain access to a protected service on the CA Single Sign-On Policy Server version 12.0 running in FIPS-only mode.
The Administrator is responsible for installing and configuring the CA Single Sign-On R12 Custom Assertion package on the Gateway. For more information, refer to the
Custom Assertion Installation Manual
. If you encounter authentication errors during the execution of a policy, refer to "Troubleshooting" below.
(1) You may receive an HTTP Basic authentication warning when the CA Single Sign-On R12 Protected Resource assertion is used with these assertions: Require XPath Credentials, Require FTP Credentials, or Require WS-Security UsernameToken Profile Credentials. You may ignore this policy validation warning. (2) When used in a policy that includes the Require HTTP Basic Credentials and Require HTTP Cookie assertions, ensure that the "HTTP Basic" assertion comes
after
 the "HTTP Cookies" assertion. (3) When running this assertion in the browser client, a triangular warning icon (Exclamation_in_triangle.png) may appear next to the dialog box when the assertion properties is displayed. You may ignore this icon.
Context Variables Created by This Assertion
See "Authenticate with CA Single Sign-On R12 Assertion" under Context Variables for CA Single Sign-On.
Usage Rules
Note the following rules when using the CA Single Sign-On R12 Protected Resource assertion:
  • The Authenticate with CA Single Sign-On R12 Protected Resource assertion cannot be used with:
    • Authentication assertions that encrypt passwords, such as the Require SSL or TLS Transport with Client Authentication assertion
    • The Sign Element and Encrypt Element assertions
    • The Authenticate User or Group assertion
  • The Authenticate with CA Single Sign-On R12 Protected Resource assertion can be used with:
    • The Require HTTP Basic Credentials assertion
    • Require SSL or TLS Transport assertion
    • Any other assertion not listed in the above list.
  • A policy should contain only a single Authenticate with CA Single Sign-On R12 Protected Resource assertion per authentication scheme. However, multiple occurrences of this assertion is possible in complex policies that contain multiple authentication schemes.
Note: You may receive a warning when the assertion is used multiple times on one policy path ("Warning: You already have an access control Custom Assertion in this path.") You may ignore this policy validation warning.
  • In a policy, the Authenticate with CA Single Sign-On Protected Resource R12 assertion should appear before the routing assertion and after the Require SSL or TLS Transport with Client Authentication Assertion and authentication method assertions.
Using the assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Adding an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click
    Authenticate with CA Single Sign-On R12 Protected Resource
    in the policy window and choose
    Authenticate with CA Single Sign-On R12 Protected Resource
     or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure the dialog as follows:
    Setting
    Description
    Agent ID
    Enter the name of the CA Single Sign-On Agent to use. The name may be omitted when only one agent is configured.
    Protected Resource
    Enter the name of the resource being protected by the CA Single Sign-On Policy Server.
    Action
    Enter the action (such as “POST” or “GET”) for the protected resource. The default action is
    POST
    .
    Authorize via CA Single Sign-On Cookie
    Specify how authorization should occur:
    • Select this check box to have the assertion attempt to gather a valid CA Single Sign-On cookie and place it in the HTTP Response.
    • Clear this check box to not add a CA Single Sign-On cookie to the HTTP Response.
    If authorizing via CA Single Sign-On Cookie, specify how to obtain the cookie:
    • Use cookie from request:
       Choose this option to have the assertion attempt to gather the CA Single Sign-On cookie from the HTTP Request and add it to the HTTP Response with the name specified in the adjacent field.
    Default CA Single Sign-On cookie name:
    SMSESSION
    • Use cookie from variable:
       Choose this option to have the assertion attempt to gather a valid CA Single Sign-On cookie from the context variable specified in the adjacent field (in the format "${
      cookieName
      }".
    The Gateway will log audit code 8001 if a valid cookie could not be found.
    The action and resource values are determined by the settings in the realm that is used by the Gateway custom agent in the CA Single Sign-On Policy Server. Consult your Administrator for information about the action and resource properties.
  4. Click [
    OK
    ] when done.
Troubleshooting
If configuration errors exist in the CA Single Sign-On Policy Server or the Gateway, then one of the following error messages will appear in the Gateway Audit Events window when the CA Single Sign-On R12 Protected Resource assertion is used in a policy.
Contact your Administrator if you encounter authentication errors.
Error Message
Description
SEVERE: Unable to connect to the CA Single Sign-On Policy Server
This error message appears when:
  • The CA Single Sign-On Policy Server is down
  • The Gateway is not properly configured to connect to the CA Single Sign-On Policy Server
  • The connection credentials cannot be read properly because the hashed cookie that is presented to the CA Single Sign-On Policy Server cannot be decrypted.
An error message indicating a CA Single Sign-On Agent initialization failure is also displayed. Verify the CA API Gateway and CA Single Sign-On Policy Server connection settings.
SEVERE: The CA Single Sign-On Agent name and/or the secret is incorrect
This error message appears when the agent name and/or the secret is not configured correctly.
WARNING: Authorization (access control) failed
This error message appears when the Gateway connection credentials are not authenticated or authorized by the CA Single Sign-On Policy Server. You will be prompted to re-enter your user name and/or password. Ensure that the user name and password entered in the CA API Gateway - XML VPN Client match those configured in the user database used by the CA Single Sign-On Policy Server to authenticate and authorize users.
The following error messages relate to port numbers defined in the
siteminder12.agent.configuration
 cluster property. For detailed information about this cluster property, see "Installing the CA Single Sign-On Assertion" in the
Custom Assertions Installation Manual
.
SEVERE: Siteminder configuration error: authentication port not defined
This error message appears when the authentication port is not defined properly.
SEVERE: Siteminder configuration error: authorization port not defined
This error message appears when the authorization port is not defined properly
SEVERE: Siteminder configuration error: accounting port not defined
This error message appears when the accounting port is not defined properly

Content feedback and comments