Skip to content
CA Single Sign-On - 12.52 SP1
Documentation powered by DocOps

Configuring the Authentication and Authorization Web Services

Last update April 17, 2019


CA Single Sign-on currently offers an authentication web service and an authorization web service. To work with the authentication and authorization web services, perform the following steps:

  1. Create the ACO.
  2. Enable the Web Services.
  3. Protect the Web Services.
  4. Configure the Web Service Logs.
  5. (Applications Programmer) Create the Client Program

Contents

Overview of the Authentication and Authorization Web Services

The CA Single Sign-on authorization and authentication web services are part of the CA Access Gateway installation. You can enable or disable them individually.

The web services configuration process presupposes configuration of the following CA Single Sign-on objects:

  • One or more agents to protect target applications against which callers authenticate
  • Realms, user directories, policies, and responses that are required for authentication and authorization

You can use the authentication and authorization web services to support an application that is not otherwise protected. A free-standing application on a mobile phone, for example, can authenticate a user when the appropriate CA Single Sign-on objects are available.

These web services support the SOAP 1.2 protocol and the HTTP-based RESTful architecture using the POST method. The authentication and authorization web services provide the following functionality:

  • login -- Authenticates and returns a session token when the authentication is successful.

    Note: If the Enable User Tracking option is enabled, the response contains an identity token additionally.
  • blogin -- Authenticates and verifies whether the login is successful; does not return a session token.
  • logout -- Logs out the user or group of users.
  • authorize -- Returns an authorization status message and a refreshed session token.

The response to a request of an operation is dependent on the corresponding CA Single Sign-on generated headers. If a resource is protected with the Anonymous authentication scheme, the response does not contain a session token but contains an identity token. The identity token can be used in the subsequent authorization request instead of a session token.

An authentication request includes the following parameters:

  • appId
  • resource string
  • action
  • user credentials

The appId references a user-defined logical name for the location of a hierarchy of resources, not a CA Single Sign-on Application object. Internally, the appId maps to an agent. CA Single Sign-on uses the agent name to determine the realm. The realm, the resource string, and user credentials are enough to authenticate the user.

An authorization request is simpler than an authentication request. The authorization request includes an appId, resource path, action, and session token, obtained from the login response. The web service validates the token and determines whether to grant access to the specified resource.

Configure the Web Services

By default, the web services feature is installed when you install or upgrade to CA Access Gateway.

To configure the web services, perform the following steps:

  1. Create an ACO for the web services through WAMUI.
  2. Protect the web services.
  3. Enable the web services through Administrative UI.
  4. (Optional) Configure the web services logs.

Create an ACO for the Web Services

You can manage the web services through an ACO. To use the web services, you must enable the enableauth parameter or the enableaz parameter or both.

Follow these steps:

  1. Create an ACO that is based on the AuthAzServiceDefaultSettings template in WAMUI.
  2. Configure the following parameters:
    • AgentName
      Defines the names of the web agent that protects a resource. You can define one or more web agents where each web agent protects an application. Enter a multi-value pair in the following format:

      agent_name,appID


      • agent_name
        Defines the name of the web agent that protects a resource.
      • appID
        Defines the reference name of the web agent that was specified in agent_name or of the application that is protected by the web agent. CA Single Sign-on uses this value in the web services requests, thus protecting the agent name from the users.
    • enableauth
      Specifies the status of the authentication web service. If you want to use the authentication web service, set the value to yes.
    • enableaz
      Specifies the status of the authorization web service. If you want to use the authorization web service, set the value to yes.
    • RequireAgentEnforcement
      Specifies whether the web services must be protected by a CA Single Sign-on agent. Set this value to yes and protect the web services by a CA Single Sign-on Agent. If you set the value to yes and the web services are not protected, the requests to web services fail.


  3. Save the changes.

Enable the Web Services

Use the ACO that you created in the previous procedure to enable the web services through Administrative UI.

Note: If the values of enableauth and enableaz are set to no, the web services do not function even though you enable the support through CA Access Gateway Admin UI.

Follow these steps:

  1. Navigate to Web Services, Auth and Az Web Services.
  2. Enable the Auth and Az Web Services option.
  3. Type the unique host name of the web services virtual host in Host Name.
    Note: Ensure that you specify a correct FQDN. CA Access Gateway creates a virtual host and enables the web services.
  4. Type the name of the ACO that is created for the web services in Agent Configuration Object.
  5. Click Save.
    The web services are enabled.

Protect the Web Services

We recommend that you protect the web services. Protecting the web services lets CA Single Sign-on authenticate and authorize the web services client before a user request is processed. When you protect the web services in your production environment, CA Access Gateway includes the SMSESSION cookie into the user request. If the RequireAgentEnforcement ACO parameter is enabled, the user request is verified for the SMSESSION cookie before processing the user request.

You can protect the root URL of the web services using the Basic authentication scheme or X.509 Client Certificate authentication scheme. We recommend that you use the X.509 Client Certificate authentication scheme.

To protect the authentication and authorization web service using a basic authentication scheme, perform the following steps:

  1. Create a basic authentcation scheme for the web service.
  2. Protect the authentication and authorization web service root URL with the basic authentication scheme created in Step 1.

For more information about using the basic authentication, see How to protect Auth/Az Web services with Basic Authentication.

To access the protected web service client request, perform the following steps:

  1. Combine the username and password into the username:password string format.
  2. Encode the string using Base64.
  3. Send the encoded string in the header in the following format:

    Authorization: Basic encoded_string

To protect the authentication and authorization web service using an X.509 Client Certificate authentication scheme, perform the following steps:

  1. Create an X.509 Client Cert authentication scheme for the web service with the following Server Name:
    Server Name
    Defines the FQDN host name of the web service virtual host that you created in CA Access Gateway.
  2. Protect the web service root URL with authentication scheme created in Step 1.
  3. Create a certificate mapping for the root certificate in CA Single Sign-On Administrative UI.

To access the protected web service client request, you must send the X.509 client certificate along with the web service request. If a user accesses with a valid client certificate, the request is validated and the web service is accessed.

For more information about using the X.509 Certificate authentication scheme, see CA Access Gateway:Auth/AZ Web Service with Certificate Authentication and CA Access Gateway:X.509 Cert Authentication.

Configure the Web Services Logs

When you enable the web services, CA Access Gateway saves the logs of the web services in the server.log file. You can change the log location from server.log to authazws.log.

If you want to change the log location, perform the following steps:

  1. Navigate to sps_home/proxy-engine/conf/webservicesagent.
  2. Take a back-up of the file authaz-log4j.xml.
  3. Open the original authaz-log4j.xml file, and perform the following steps:
    1. Uncomment the following AuthAZ_ROLLING appender tag:

      <appender name="AuthAZ_ROLLING" class="org.apache.log4j.DailyRollingFileAppender">
      <param name="File" value="logs/authazws.log"/>
      	<layout class="org.apache.log4j.PatternLayout">
      	<param name="ConversionPattern" value="%d %-5p [%c] - %m%n"/>
      </layout>
      </appender>
      
    2. Uncomment all the occurrences of the following appender-ref for the AuthAZ_ROLLING tag:

      <appender-ref ref="AuthAZ_ROLLING"/>
      
  4. Save the changes and restart CA Access Gateway.
    The log location is changed to the authazws.log file, which is located in sps_home/proxy-engine/logs/.

Create the Client Program

The function of the client program is to issue authentication and authorization requests to the web service on behalf of another application. The client program requires code for a client stub. The stub manages, sends, and receives messages to communicate with the web service. The web service support a WSDL file (for the SOAP protocol) and a WADL file (for the REST architecture). You can access the WSDL or WADL file using a web browser, and then save it as an XML file.

Follow these steps:

  1. Write the business logic for your application, which gathers the required credentials.
  2. Create the client stub. Optionally, you can use the WSDL or WADL file with a third-party tool to generate the client stub.
    • To load the WSDL, use the following URL:

      http://hostname:port/authazws/auth?wsdl

    • To load the WADL, use the following URL:

      http://hostname:port/authazws/AuthRestService/application.wadl

    Note: To retrieve the metadata from these locations, be sure to set the DefaultAgentName parameter in the ACO to one of your agents.
  3. Import the client stub and instantiate the stub object to invoke the web service.

The sections that follow list simplified sample SOAP and REST messages for reference.

Authentication SOAP Interface

These simplified samples show authentication works using the SOAP protocol. Most authentication schemes can be supported by an IdentityContext consisting of just three fields, username, password, binaryCredentials. Other schemes, requiring more fields are supported by additional operations whose inputs are tailored to the credential type.

The following example is an authentication web service normal user login request:

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:aut="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
   <s:Header/>
   <s:Body>
     <aut:login>
       <identityContext>
         <userName>user1</userName>
         <password>user1</password>
         <binaryCreds></binaryCreds>
       </identityContext> 
       <appId>app1</appId>
        <resource>/*</resource>
       <action>GET</action>
       <sessionToken></sessionToken>
     </aut:login>
   </s:Body>
   </s:Envelope>


The blogin operation (Boolean Login) is similar to the login operation. However, blogin does not return a SMSESSION value in the response, as shown in the following example:

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:aut="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
   <s:Header/>
   <s:Body>
     <aut:blogin>
       <identityContext>
        <binaryCreds>
        </binaryCreds>
        <password>user1</password>
        <userName>user1</userName>
       </identityContext> 
       <appId>app1</appId>
       <action>GET</action>
       <resource>/*</resource>
    </aut:blogin>
  </s:Body>
  </s:Envelope>


The following example represents a successful login response:

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope">

  <s:Header/>
 <s:Body>
    <aut:loginResponse xmlns:aut="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
     <return>
       <message>Authentication Successful</message>
       <resultCode>LOGIN_SUCCESS</resultCode>
       <sessionToken>session</sessionToken>
       <authenticationResponses>
         <response/>
         <response/>
       </authenticationResponses>
     </return>
    </aut:loginResponse>
  </s:Body>
</s:Envelope>


The following example represents a failed login attempt:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns2:loginResponse xmlns:ns2="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
       <return>
          <message>Authentication Failed</message>
          <resultCode>LOGIN_FAILED</resultCode>
          <authenticationResponses>
             <response>
             </response>
          </authenticationResponses>
       </return>
     </ns2:loginResponse>
   </S:Body>
</S:Envelope>


The following example represents an authentication web service user logout request:

Note: Even though a user has successfully logged out, the agent can still use the SessionToken to authorize, because it is considered to be a valid user credential.

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:aut="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
   <s:Header/>
   <s:Body>
     <aut:logout>
       <sessionToken>session</sessionToken>
     </aut:logout>
   </s:Body>
</s:Envelope>


The following example represents a successful authentication web service logout response:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns2:logoutResponse xmlns:ns2="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
       <return>
          <message>Logout Successful</message>
          <resultCode>LOGOUT_SUCCESS</resultCode>
       </return>
    </ns2:logoutResponse>
  </S:Body>
</S:Envelope>

Authentication REST Interface

REST means REpresentational State Transfer. In REST, service requests transform the state of objects accessible by URIs. HTTP drives state change using actions such as create, read, update, and delete.

The URI mapping for authentication and authorization consists of the appId and resourcePath. The resource state is the collections of authenticated or authorized users associated with the Resource. The service names for authentication are login, blogin, and logout.

A URI in this format, http://hostname:port/authazws/AuthRestService/login/appID/Resource, posts the following request:

<loginRequest>
      <binaryCreds></binaryCreds>
       <password>user1</password>
       <userName>user1</userName>
       <action>GET</action>         
</loginRequest>

The login responses:

HTTP return code 200

<loginResponse>
<message>Authentication successful</message>
<resultCode>LOGIN_SUCCESS</resultCode>
<sessionToken>session</sessionToken>
<authenticationResponses>
	<response>
		<name>SM_SESSIONDRIFT</name>
		<value>0</value>
	</response>
</authenticationResponses>
</loginResponse>

HTTP return code 400

<loginResponse>

<message>Bad Request</message>
<resultCode>LOGIN_ERROR</resultCode>
</loginResponse>

HTTP return code 200

<loginResponse>
<message>Authentication Failed</message>
<resultCode>LOGIN_FAILED</resultCode>
<authenticationResponses>	
	<response><name>SM_AUTHREASON</name>
	<value>0</value>
	</response>	
</authenticationResponses>
</loginResponse>

HTTP return code 500

<loginResponse>
<message>System</message>
<resultCode>Server Error</resultCode>
</loginResponse>

The bLogin operation (Boolean Login) is similar to login. A URI in this form, http://host:port#/blogin/appId/resourcePath posts as shown in the login request. It returns yes or no in the response message.

A URI in this format, http://host:port#/authazws/AuthRestService/logout/, posts the following the logout request:

<logoutRequest>
<sessionToken>session</sessionToken>
</logoutRequest>


The authentication web service logout responses:

<logoutResponse>
   <message>Logout Successful</message>
   <resultCode>LOGOUT_SUCCESS</resultCode>
</logoutResponse>


<logoutResponse>
   <message>Logout Failed</message>
   <resultCode>LOGOUT_FAILURE</resultCode>
</logoutResponse>

Authorization SOAP Service

The following XML approximates an authorization request to the web service:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aut="http://ca.com/2010/04/15/authorization.xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <aut:authorize>         
	<sessionToken>session</sessionToken>
           <appId></appId>         
           <action>GET</action>            
	 <resource>/domainAdmin/a.jsp</resource>         
      </aut:authorize>
   </soapenv:Body>
</soapenv:Envelope>

You can replace GET with POST in the action.

The following example represents an authorization web service AUTHORIZED response:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns2:authorizeResponse xmlns:ns2="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
      <return>
        <message>Authorization successful</message>
        <resultCode>AUTHORIZED</resultCode>
        <sessionToken>sWNuJjptq1XhS</sessionToken>
        <authorizationResponses>
         <response> 
         </response>
    </authorizationResponses>
   </return>
  </ns2:authorizeResponse>
 </S:Body>
</S:Envelope>


The following example represents an authorization web service UN AUTHORIZED response:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns2:authorizeResponse xmlns:ns2="http://www.ca.com/siteminder/authaz/2010/04/15/authaz.xsd">
      <return>
        <message>Authorization Failed</message>
        <resultCode>NOTAUTHORIZED</resultCode>
        <authorizationResponses/>
      </return>
    </ns2:authorizeResponse>
  </S:Body>
</S:Envelope>

Note: For an authorization web service request with a valid session token, the NOTAUTHORIZED authorization response has the following constraints:
  1. You can configure the response with only the following attributes in the WAMUI:
    • SM_ONREJECTTEXT
    • SMREDIRECTURL or SM_REDIRECTURL
    • SMERROR
  2. The response does not contain a session token.

Authorization REST Interface

The REST interface for authorization is http://hostname:port/authazws/AuthRestService/authz/appID/Resource:

<authorizationRequest>
<action>POST</action>
<resource>RealmA/index.html</resource>
<sessionToken>affl;;alkf;l;fd</sessionToken>
</authorizationRequest>


HTTP return Code 200:

<authorizationResult>
   <message>Authorization successful</message>
   <resultCode>AUTHORIZED</resultCode>
   <sessionToken>session</sessionToken>
   <authorizationResponses>
      <response>
         <name>SM_USERDN</name>
         <value>uid=user3,ou=People,o=security.com</value>
      </response>
   </authorizationResponses>
</authorizationResult>

Was this helpful?

Please log in to post comments.