API Programming Guide › API Authentication

API Authentication

Your API calls must be authenticated to access the CA User Activity Reporting Module event log store. Here are several ways to set up authentication:

Using a valid CA User Activity Reporting Module user name and password as part of the authentication URL. When constructing a call, verify that the information you want is available to the user account you want to use to authenticate.
Using a certificate name and certificate password as part of the authentication URL. You can create a certificate from the API product registration interface.
Using a session ID as part of the authentication URL. This session ID is a unique ID returned as part of the XML response after a successful authentication call. Use one of the other authentication methods to derive a session ID, which you can then use to create another session.

User Name and Password Example

https://ELMSERVER:5250/spin/calmapi/getObject.csp?type=getQueryList&username=xx&password=xx

This example uses the getQueryList command, and authenticates using a CA User Activity Reporting Module user name and password.

Certificate Name and Password Example

https://ELMSERVER:5250/spin/calmapi/getObject.csp?type=getELMServers&certname=xx&password=xx

This example uses the getELMservers command, and authenticates using a certificate name and password.

Session ID Example

https://ELMSERVER:5250/spin/calmapi/getObject.csp?type=getQueryViewer&objectId=Subscription/panels/System_Event_Count_By_Event_Action&sessionID=xxxxx

This example uses the getQueryViewer command, and authenticates using a session ID.

More information:

API Login

API Certificate Creation

API Login

This call authenticates a user using a set of CA EEM credentials, a certificate, or a session ID.

Because you can include authentication information in any API call URL, you do not need a separate login call in most cases. The login call is most useful for returning a Session ID, which can then be used to authenticate another call, such as getReportViewer.

The arguments used for this call are as follows:

username: Defines the valid CA User Activity Reporting Module user name for authentication.
certname: Defines the certificate name for authentication, if you have registered the product you want to access CA User Activity Reporting Module.
password: Defines either the CA User Activity Reporting Module user password, or the certificate password for authentication, depending on which method you have used for authentication.
sessionid: Defines the session ID from an existing authenticated session, which you can use to authenticate a new session.

API Login Examples

Command:

https://ELMSERVER:5250/spin/calmapi/calmapi_login.csp&username=xx&password=xx

Success Response:

  <?xml version="1.0" encoding="UTF-8" ?> 
 <Result>
  <Value>true</Value> 
  <Description>Authentication Successful.</Description>
  <SessionId>spin=62e39751-computername.domain.com49b8a97e-9bfd318-1</SessionId> 
  </Result>

The session ID opened by the login appears in the <SessionId> tag.

Failure Response:

<?xml version="1.0" encoding="UTF-8" ?> 
<Result>
<Value>false</Value>
	<Description> EE_AUTHFAILED Authentication Failed</Description>
</Result>

More information:

Query and Report Viewer Calls

API Authentication

API Logout

This call ends an API session by logging out a user, ends a certificate session, or ends a session created through session ID. The call accepts no arguments.

API Logout Examples

https://ELMSERVER:5250/spin/calmapi/calmapi_logout.csp

Success Response:

<?xml version="1.0" encoding="UTF-8" ?> 
<Result>
<Value>true</Value>
	<Description>Logout Successful</Description>
</Result>

Failure Response:

<?xml version="1.0" encoding="UTF-8" ?> 
<Result>
<Value>false</Value>
	<Description> User is not logged in</Description>
</Result>
UTHFAILED Authentication Failed</Description>
</Result>

About API Sessions

CA User Activity Reporting Module creates a session each time you use an API call. The persistence of these sessions differs depending on the authentication method you use:

User name and password, or session ID-authenticated sessions expire in the same way CA User Activity Reporting Module sessions do, using the Session Timeout value, which is set at 15 minutes by default. You can set the Session Timeout value from the CA User Activity Reporting Module interface.
Certificate-authenticated sessions do not expire except in certain circumstances. The Session Timeout value is suspended, which lets you integrate CA User Activity Reporting Module with a web portal or outside product more easily. However, it can require additional action to avoid unnecessary use of system resources by persistent sessions.

CA User Activity Reporting Module closes certificate-authenticated sessions under the following circumstances:

Closing a browser displaying a graphic component such as a query
Logging out of an outside product
Allowing the user session of an outside product to expire,

The CA User Activity Reporting Module session timer begins to count down, and ends the session after the timeout value you have configured expires.

If many getQueryViewer or getReportViewer calls are in use, there can be a number of open but idle sessions. To reduce the system resources used by such sessions, use the logout command to end a session when an outside product user logs out, or an outside product session ends.