Security framework for HCL Marketing Software APIs

Marketing Platform provides the security framework for the APIs implemented by HCL® Marketing Software products.

A set of configuration properties on the Settings > Configuration page enables developers to set the following security for the APIs provided by HCL Marketing Software products.

  • For a specific product API, you can block access to the product.
  • For a specific product API, you can require HTTPS for communication between the specified API and the product.
  • For a specific product API, you can require authentication for communication between the specified API and the product.

The configuration properties that control API security are located under the IBM Marketing Platform | Security | API management category. Each product has a configuration property template that you can use to create new security settings for the APIs provided by that product.

You can set and change the security settings for an API as appropriate for unit testing or deployment or during the overall lifecycle of APIs.

The security framework currently supports APIs for Campaign only.

The Marketing Platform security framework supports the following two authentication options for accessing protected APIs. You can use either one, depending on your environment.

  • Internal users who are registered with Marketing Platform can be authenticated using their Marketing Platform login credentials to obtain a secure token.
  • External users who are part of a federation that Marketing Platform is set up to use can be authenticated though the Identity Provider server.

Internal user authentication with the Marketing Platform login API

To authenticate internal users in client applications, use the Marketing Platform login API to generate secure tokens. You can then invoke any protected APIs by passing the required parameters in the request header, in addition to the parameters expected by the API itself.

The security filter intercepts these protected requests, validates them, and then passes them through for processing.

After the Marketing Platform user is authenticated, the Marketing Platform security filter adds the user's login name to the request as an attribute of the USER_NAME_STRING key before passing it to the product for processing.

The secure tokens have a default life span of 15 seconds. After the life span of the token expires, it cannot be used to invoke a protected API. Each time the Marketing Platform login API is invoked for a user, all previous security tokens for that user are invalidated.

You can change the life span of secure tokens by setting the value of the Token lifetime property located on the Settings > Configuration page under the General | Miscellaneous category.

Example URL

http[s]://host:port/unica/api/manager/authentication/login/

Header parameters

Table 1. Header parameters for the login API with internal users
Parameter Description
m_user_name The internal user's Marketing Platform login name.
m_user_password The internal user's Marketing Platform password in plain text.

Response

When login succeeds, the response is HTTP 200 with the following JSON data.

  • m_tokenId - randomly generated token
  • m_user_name - user name of the logged in user
  • createDate - timestamp in the format that is shown in the following example, where the time zone is IST:

    Mon Jul 06 18:23:35 IST 2015

When login fails with bad credentials, the response is HTTP 401 (unauthorized). When the login API is configured to be blocked, the response is 403 (forbidden). When the login API is configured to use HTTPS and if it is invoked on HTTP, the response is 403 (forbidden).

To log out internal users, use the Marketing Platform logout API.

Internal user logout with the Marketing Platform logout API

Use the Marketing Platform logout API to log out internal users and delete the secure token.

The logout API is protected by default. The authentication parameters are expected in the request header against pre-defined keys.

Example URL

http[s]://host:port/unica/api/manager/authentication/logout/

Header parameters

Table 2. Header parameters for the logout API
Parameter Description
m_user_name The internal user's Marketing Platform login name.
m_tokenId The secure token obtained through authentication.
api_auth_mode Use the value manager for internal users.

Response

When authentication succeeds, the response is HTTP 200, and the secure token is deleted. If the response is HTTP 200, the client application should confirm the logout.

When authentication fails, the response is HTTP 401.

External user authentication and logout through a federation

When Marketing Platform is integrated with a supported federation, users can log in to their own system, and the client application gets a token through the Identity Provider (IdP) server provided by Marketing Platform.

After a federated user is authenticated, their corresponding Marketing Platform login name is added to the request as an attribute of the USER_NAME_STRING key.

Log out should be done at the IdP server.

Header parameters

The following table describes the header parameters to use when authenticating through the IdP server provided by Marketing Platform.

Table 3. Header parameters with a federation
Parameter Description
f_userId User ID in the federation.
f_clientId Client ID in the federation.
f_spId Service provider ID in the federation.
f_tokenId Single sign-on token from the IdP server.
api_auth_mode Use the value fsso for federated authentication.

Response

The response is HTTP 200, with additional items depending on the API.