The attribute collection service is a Representational State Transfer (REST) service. It
can collect web browser and location information from the user for calculating the risk
score.
Process overview
The following process describes the attribute collection service and how to use it:
- Make REST calls to store and delete attributes in the database. The initial request to the
service receives a correlation ID. The correlation ID is used to make further REST calls.
- Use JavaScript to collect the web
browser attributes. You can place the HTML page that calls the JavaScript functions on any server.
- Ajax collects information in the background. It does not slow down page loading.
- You can make standard Ajax requests only to the same domain. With Cross Origin Resource Sharing
(CORS), you can make Ajax requests across domains.
- The CORS response header contains the settings for the following specifications:
- The server from which requests are accepted.
- The types of requests that are accepted.
Attributes that are configured as session attributes are collected automatically by the
info.js file for risk score calculation.
Request
types
GET
and POST requests create a correlation ID to identify the session in the database. A correlation ID
is a UUID that is stored in a cookie. The attribute collection service process uses the following
request types:
- GET
- Retrieves information about an attribute session from the database. GET
requests are disabled by default. Requests use a URL with a REST path, such as:
https://webseal/mga/sps/ac/rest/UUID.
- POST
- Creates an attribute session in the database. POST requests use a URL such as
https://webseal/mga/sps/ac/UUID.
The
session attributes are sent as a JSON string with the request. In a response, the
server sets a cookie that contains the correlation ID. For example, the POST
/sps/ac/9d37e806-24cf-4398-a3b9-d7f13fb2231f request creates a session in the database
with a UUID of 9d37e806-24cf-4398-a3b9-d7f13fb2231f.
You can also
configure the risk-based access properties to use an existing cookie
- DELETE
- Deletes an attribute session from the database.
Risk-based access runtime properties
Use the local management interface to configure the risk-based access properties that are
required for attribute collection service.
The following properties specify information about the attribute collection service:
- attributeCollection.cookieName
- Correlation ID used by the attribute collector.
- Data type: String
- Example:
ac.uuid
- attributeCollection.requestServer
- Request server for attribute collector. A list of the allowable hosts where the ajaxRequest can
be sent from.
- Data type: String List
- Example:
https://rbademo.example.com,https://rbaemo2.example.com
- attributeCollection.serviceLocation
- Location of the attribute collector.
- Data type: String List
- Example:
http://rbademo.example.com/mga
- attributeCollection.sessionTimeout
- Number of seconds in which sessions stored in context-based access will automatically expire,
unless updated. If any attribute in the session is updated, the session expiry is extended by the
specified number of seconds configured in this property. The default is 3600
seconds.
- Data type: Integer
- Example:
3600 seconds
- attributeCollection.enableGetAttributes
- Enables the REST GET method to return attributes.
- Data type: Boolean
- Example:
False
- attributeCollection.getAttributesAllowedClients
- A comma-separated list of clients that are allowed to access the ACS REST GET method.
If this
property is not set and attributeCollection.enableGetAttributes is set to
true, anyone can access the GET method. If
this property is set but attributeCollection.enableGetAttributes is set to
false, this property is ignored.
- Data type: String List
- Example:
hostname1, hostname2
- attributeCollection.hashAlgorithm
- The algorithm that is used to create the hash.
- Data type: String
- Example:
SHA256
- attributeCollection.attributesHashEnabled
- A comma-separated list of attribute URI values that have been configured for hashing.
- Data type: String List
- Example:
urn:ibm:security:environment:http:userAgent,
urn:ibm:security:environment:deviceFonts,
urn:ibm:security:environment:browserPlugins
- attributeCollection.authenticationContextAttributes
- Comma-separated lists of attribute names to be collected when performing an authentication
service obligation.
- Data type: String List
- Example:
authenticationLevel, http:host
JavaScript functions
Use the JavaScript functions in the
C/ac/info.js file to make requests to the server. Include the
info.js
JavaScript file in the HTML landing
page of your application. When info.js is loaded, it calls the following
functions:
- sendSession()
Makes a POST request to the delegate service.
The sendSession() function
collects the web browser attributes and sends them to the server.
They are stored in the database. Call this function when a user logs
in.
- deleteSession()
Makes a DELETE request for a specified correlation
ID.
The POST request from the sendSession() returns
a correlation ID. Based on the correlation ID, the deleteSession() function
deletes the attributes from the database. Call this function when
the user logs out or when the current session times out.
- getLocation()
- Detects the location of the device from which the requests are made. If the location information
is sent to the server, call the getLocation() function before the
sendSession() function. The following web browsers support the detection of
location: Mozilla Firefox, Google Chrome, Opera, Apple Safari, and Microsoft Internet Explorer 9 and 10.
Note: For the JavaScript functions to work in Microsoft Internet Explorer,
include the following statement in the
HTML page
from which you call the function. The following statement forces Microsoft Internet Explorer
to use the standards mode:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
For configuration steps and examples, see Configuring the attribute collection service.