Single sign-on by using a custom HTTP header

IBM® Safer Payments can be integrated into a single sign-on environment by using a custom HTTP header.

IBM Safer Payments can be used with any authentication protocol. It does not need to directly support any of the authentication protocols. Therefore, it can typically be integrated in any single sign-on environment. The authentication is handled by the authentication server, for example, ISAM, OIDC, OAuth, SAML, and so on. If the user is successfully authenticated, all requests to IBM Safer Payments need to be enriched by a configurable custom HTTP header that must contain the user name of the authenticated user. The HTTP communication should be secured by mutual authentication between IBM Safer Payments and the authentication proxy server. If the user name exists within IBM Safer Payments, the authentication is successful. If not, access with the user name is not possible.

Note: External authentication services are out of scope of IBM Safer Payments. If you opt to implement the authentication by using a custom HTTP header, you must implement proper procedures to secure this feature against unauthorized access. Enabling this authentication method triggers a notification inside the IBM Safer Payments PCI report. You must ensure the integrity and the safety of the networks that are used for this process. To initially set up IBM Safer Payments, the integrated login mechanism must be used.

Preliminary considerations

If you choose to use a custom HTTP header for user authentication, you must ensure that the external authentication server addresses all applicable PCI DSS requirements to achieve compliance. IBM Safer Payments must be set up to perform a client certificate validation on the API to secure the communication between the application and the external authentication server. See Configuring SSL encryption for details.

Before you activate the custom HTTP header authentication in IBM Safer Payments, you must configure the external authentication server to properly send the required HTTP header to the application. Otherwise, you are no longer able to login and must manually revert the configuration change on the file system.

Note: The user creation workflow in IBM Safer Payments must be used to create more users. PCI DSS requirement 8.2.1 mandates the usage of unique user IDs for each user.

Setting up custom HTTP header authentication in IBM Safer Payments

  1. In the user interface, click the Administration tab.
  2. Select System > Configuration from the navigation menu.
  3. Locate the Authentication Settings section.
    Figure 1. Authentication Settings
    This image is explained in the surrounding text.
  4. First, select OIDC claim from the Authentication method drop-down list. Then specify the Token name and the Username attribute.

    In the Token name field, you must specify the name of the HTTP header field that contains the JSON payload. Whereas in the Username attribute field, you must specify the identifier inside the JSON payload that contains the user’s login name.

  5. Save your changes.
    Attention: Check the token name and the username before saving, or you are locked out of IBM Safer Payments.

After this system configuration is saved, IBM Safer Payments accepts user logins by using the custom HTTP header. Other authentication mechanisms are no longer possible until you change the authentication settings again.

The following code shows an example HTTP header.

{
    "login_name": "jsmith@exampleMail.com",
    "last_name": "Smith",
    "first_name": "Jane", 
    "id": "cl.jsmith", 
    "internal_id": "25", 
    "emails": {
       "personal": "jsmith@personalMail.com", 
       "business": "jsmith@businessMail.com"
    },
    "phone_numbers": {
       "business": "555-555-1234"
    }
}

If you enable the custom HTTP header as an authentication method, a notification will be added to the built-in PCI report.