Account Protection Integration Guide

August 15, 2024 15:41

This integration guide includes a high-level overview of integration points, workflow, and detailed technical specifications for relevant SDKs and the corresponding API.

Login Event Workflow

The login workflow begins with data collection from the browser application or from the mobile SDK. The Kount browser data collector is a JavaScript SDK downloaded at runtime. Our mobile SDK can be integrated into your mobile application. Only one data collection should be made per session.

After your end user’s sign-in credentials have been posted to your authentication service, there are two paths:

Valid Credentials — If your end user presented valid credentials, you POST to the Kount Login API prior to granting access. The response to this API call is Allow, Block, or Challenge. Depending on the response and based on your policies, you can either allow access, deny access, or challenge your end user using the Kount MFA or your existing step-up authentication.
Invalid Credentials — If your end user fails authentication, you decline access and POST to the Failed Attempt API.

Trusted Device Workflow

The Trusted Device Service may store a trust relationship between a device and a specific user.

Users typically employ a small handful of devices to log in (a cell phone, a work laptop, and a home computer). By identifying these devices for specific users, the customer may reduce friction at login using policies to only challenge users with a device not already known and trusted.

Example:

You created a policy to Challenge a login coming from an end user with a device not previously trusted for that end user. Jane signs in using her new cell phone. Because this cell phone is not trusted for her, the response from the Kount Login Event API is Challenge.

You ask Jane to perform a step-up authentication (asking her to input a code sent to her from a text message). She succeeds, and is able to sign in to her account. You then send an update to Kount to trust this device for Jane. Kount stores this trust relationship so the next time Jane signs in with this device, she would not be asked for step-up authentication.

There are several purpose-built endpoints available with the Trusted Device Service.

Create Trusted Device Record: Used after an end user has met a step-up challenge and you would like to store the trust state of the device for that user.
Update Trusted Device Record: Used to alter the trust state between a device and an end user. Options include trusted or banned. Typically, this is to ensure that a specific end user cannot sign in using a specific device.
Read Trust States: Options to review information for all users connected to a device, all devices connected to an end user, or the trust state for a specific user/device pair. May be used to identify an end user before the end user has signed in to the site. Can also be used to allow typically used to display a list of trusted devices specific to the end user.
Delete Trusted Device Record: Used to delete the record of a relationship between an end user’s ID and a device. Typically used when there is a limited number of devices that can be used for a specific account and the end user wants to replace one device for a new one.

Device Data Collector Implementation

The Device Data Collector gathers information from a customer’s device by running client-side scripts and then sends that data to Kount. This passive analysis conceals the Kount 360 interaction with the customer and does not affect the customer’s experience. This data is one of the foundations of Kount 360 fraud protection.

The flow for device data collection follows this pattern:

The steps for Device Data Collector setup are:

Generate Session ID — Generates a session ID and provides it to the Device Data Collector SDK.
Device Data Collector SDK collects and sends device data — The Device Data Collector sends the collected device data to Kount 360.
Submit event data with session ID to your server — When the event data (the order, login, or new account opening data) gets submitted to your server, include the session ID that was passed to the Device Data Collector.
Send event data with session ID to Kount 360 — Pass the session ID in the call to Kount 360, along with the rest of the event data.
Associate device data and event data by matching the session ID — Kount 360 associates the device data and the event data, using the session ID that was passed to Kount 360.

Use our guided Device Data Collector Content generator or follow the steps in the Native iOS and Android SDKs article.

Device Data Collector browser recommendations

Proper placement and configuration of the browser Device Data Collector is important for gathering information to identify devices, adhere to business policies, and accurately define login risk. Incorrect placement or misconfiguration can cause limited or no data collection.

Page and Page Location

Place the Device Data Collector code in the body of the sign-in page. Kount reduces collection from the same session ID when a collection comes within 15 minutes. We recommend that you run a single data collection per session. When multiple collections are run in a single session — if the collection was placed in the header — it is possible the collection events can be mistaken as a DDOS attack, throttling all collections from your site.

Google Chrome Lazy Load

The Google Chrome Lazy Load feature defers loading images and iFrames that come below the end of the page. This feature is active when the Chrome Data Saver feature is on and when the loading attribute is set to auto or unset. If you are using the Kount legacy data collector that utilizes an iFrame, update integration or set the loading attribute to eager, which bypasses lazy loading functionality.

Content Security Policy

Kount utilizes both third-party and first-party cookies as well as device data to identify devices. In order to take full advantage of the Device Data Collector, you can make modifications to the Content Security Policy on your site. For more information on Content Security Policy, go to Content Security Policies (CSP) and the Device Data Collector.

Provisioning an API Key

Sign in to Kount 360. There are two integration environments: sandbox and production. Only integrate into our sandbox environment if you are integrating a pre-production environment without production data.
Select Admin, and then Product Configuration.
Select Options for the organization in which you want to create an API key, and then select Create API Key.
Select Create.
Expand the organization.
Copy the API key and save it in a secure location. You will need the API key to create a bearer token.

Note

Use the copy button to copy the API key. If you close the window without copying the API key, you must create a new API key using the options menu. You are allowed two active API keys per customer. To create another API key after creating two API keys, delete one of the existing keys.

Creating a Bearer Token

Following the OAuth 2.0 framework, after you have provisioned your API credentials in the portal, retrieve a temporary bearer token to authenticate calls to the Kount 360 API. Provide the API Key and Client ID in an HTTP POST to a specific login.kount.com URL.

With a successful exchange, the returned JSON provides a special bearer token, which is the access_token property. The exchange also provides an expiration date, the expires_in property, provided in seconds until expiration. The API to retrieve the bearer token depends on if you are calling the sandbox or production environment.

The values are:

Sandbox

Auth Server URL:

https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token

API Service Host:

https://api-sandbox.kount.com

Production

Auth Server URL:

https://login.kount.com/oauth2/ausdppksgrbyM0abp357/v1/token

API Service Host:

https://api.kount.com

After obtaining the bearer token, utilize it to authenticate requests to the Kount 360 API. Include the token in the Authorization header of your HTTP API request, prefixed with Bearer {bearer token}.

To prevent authentication issues, refresh the token before it expires. Typically, tokens issued by login.kount.com expire after 20 minutes, but client credentials remain valid unless revoked. Minimize calls to the /token endpoint by implementing token expiration handling in your customer applications. Always check if a token has expired before requesting a new one, as excessive calls to the /token endpoint could result in rate limiting.

Examples of retrieving and using the bearer token in popular programming languages:

Python

sidebar. Python Code Example

"""sandbox"""
import requests
AUTH_SERVER_URL = "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token"
API_URL = "https://api-sandbox.kount.com"
API_KEY = "YOUR API KEY HERE"
CLIENT_ID = "YOUR CLIENT_ID HERE"

r = requests.post(AUTH_SERVER_URL,
                  params={"grant_type": "client_credentials",
                          "scope": "k1_integration_api"},
                  headers={"Authorization": "Basic" + API_KEY,
                           "Content-Type":
                           "application/x-www-form-urlencoded"})

t = r.json()["access_token"]

r = requests.post(API_URL + "/login",
                  headers={'Authorization': "Bearer " + t},
                  json={
                    "clientId": "900900",
                    "sessionId": "d121ea2210434ffc8a90daff9cc97e76",
                    "userId": "meoyyd8za8jdmwfm",
                    "username": "meoyyd8za8jdmwfm",
                    "userPassword": "38401eb46f8fbb74c1846a5f47f68d83a9bef126b1d4143f886cd464323cdaab",
                    "userIp": "192.168.0.1",
                    "loginUrl": "http://www.example.com/login",
                    "userAuthenticationStatus": "true",
                    "userCreationDate": "2019-08-24T14:15:22Z",
                    "userType": "VIP",
                    "mfaPhone": "+12081234567",
                    "mfaEmail": "username@example.com",
                    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
                    "context": "LOGIN"
                })
print("Response:", r.json())

TypeScript

sidebar. TypeScript Code Example

const axios = require('axios')

const API = 'https://api-sandbox.kount.com'
const ISSUER = 
'https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
const CLIENT_ID = 'YOUR CLIENT ID HERE'
const API_KEY = 'YOUR API KEY HERE'

async function getBearerToken() {

    const auth = await axios({
        url: `${ISSUER}/v1/token`,
        method: 'post',
        headers: {
            authorization: `Basic ${API_KEY}`
        },
        params: {
            grant_type: 'client_credentials',
            scope: 'k1_integration_api'
        }
    })

    return auth.data.access_token
}

async function evaluateLogin(token: string) {

    const resp = await axios({
        url: `${API}/login`,
        method: 'post',
        headers: {
            authorization: `Bearer ${token}`,
        },
        data: {
            clientId: "900900",
            sessionId: "d121ea2210434ffc8a90daff9cc97e76",
            userId: "meoyyd8za8jdmwfm",
            username: "meoyyd8za8jdmwfm",
            userPassword: "38401eb46f8fbb74c1846a5f47f68d83a9bef126b1d4143f886cd464323cdaab",
            userIp: "192.168.0.1",
            loginUrl: "http://www.example.com/login",
            userAuthenticationStatus: "true",
            userCreationDate: "2019-08-24T14:15:22Z",
            userType: "VIP",
            mfaPhone: "+12081234567",
            mfaEmail: "username@example.com",
            userAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
            context: "LOGIN"
        }
    })

    return resp.data
}
const main = async () = {
    const token = await getBearerToken();
    const resp = await evaluateLogin(token);
    console.log(JSON.stringify(resp, null, 4))
}

main()

Bash

sidebar. Bash Code Example

#!/usr/bin/env bash

API='https://api-sandbox.kount.com'
ISSUER='https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
CLIENT_ID=''
API_KEY=''

# Get our token (it is valid for 20 minutes)
RESPONSE=$(curl -s -X POST "${ISSUER}/v1/token?grant_type=client_credentials&scope=k1_integration_api" -H "Authorization: Basic ${API_KEY}" -H "Content-Type: application/x-www-form-urlencoded")
TOKEN=$(echo $RESPONSE | jq -r .access_token)

# Make our evaluation request
REQUEST_DATA='{
                "clientId": "900900",
                "sessionId": "d121ea2210434ffc8a90daff9cc97e76",
                "userId": "meoyyd8za8jdmwfm",
                "username": "meoyyd8za8jdmwfm",
                "userPassword": "38401eb46f8fbb74c1846a5f47f68d83a9bef126b1d4143f886cd464323cdaab",
                "userIp": "192.168.0.1",
                "loginUrl": "http://www.example.com/login",
                "userAuthenticationStatus": "true",
                "userCreationDate": "2019-08-24T14:15:22Z",
                "userType": "VIP",
                "mfaPhone": "+12081234567",
                "mfaEmail": "username@example.com",
                "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
                "context": "LOGIN"
              }'
RESPONSE=$(curl -s -X POST ${API}/login -H "Authorization: Bearer ${TOKEN}" -d "$REQUEST_DATA")
echo "$RESPONSE" | jq

Go

sidebar. Go Code Example

package main

import (
        "bytes"
        "encoding/json"
        "fmt"
        "io"
        "net/http"
)

type config struct {
        API      string
        Issuer   string
        ClientId string
        APIKey   string
}

func getToken(c *http.Client, issuer, creds string) string {

        req, _ := http.NewRequest(http.MethodPost, issuer+"/v1/token", nil)

        req.Header.Add("Authorization", "Basic "+creds)

        req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

        q := req.URL.Query()
        q.Add("grant_type", "client_credentials")
        q.Add("scope", "k1_integration_api")
        req.URL.RawQuery = q.Encode()

        resp, _ := c.Do(req)
        defer resp.Body.Close()

        t := struct {
                TokenType   string `json:"token_type"`
                ExpiresIn   int    `json:"expires_in"`
                AccessToken string `json:"access_token"`
        }{}

        json.NewDecoder(resp.Body).Decode(&t)
        return t.AccessToken
}

func evaluate(c *http.Client, api string, payload LoginRequest, token string) string {

        j, _ := json.Marshal(payload)

        req, _ := http.NewRequest(http.MethodPost, api+"/login", bytes.NewBuffer(j))

        req.Header.Add("Authorization", "Bearer "+token)

        resp, _ := c.Do(req)
        defer resp.Body.Close()

        b, _ := io.ReadAll(resp.Body)
        s := string(b)
        return s
}

type LoginRequest struct {
        ClientID                 string `json:"clientId"`
        SessionID                string `json:"sessionId"`
        UserID                   string `json:"userId"`
        Username                 string `json:"username"`
        UserPassword             string `json:"userPassword"`
        UserIP                   string `json:"userIp"`
        LoginURL                 string `json:"loginUrl"`
        UserAuthenticationStatus string `json:"userAuthenticationStatus"`
        UserCreationDate         string `json:"userCreationDate"`
        UserType                 string `json:"userType"`
        MFAPhone                 string `json:"mfaPhone"`
        MFAEmail                 string `json:"mfaEmail"`
        UserAgent                string `json:"userAgent"`
        Context                  string `json:"context"`
}

func main() {
        config := config{
                API:      "https://api-sandbox.kount.com",
                Issuer:   "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357",
                ClientId: "",
                APIKey:   "",
        }
        client := &http.Client{}
        token := getToken(client, config.Issuer, config.APIKey)

        payload := LoginRequest{
                ClientID:                 config.ClientId,
                SessionID:                "d121ea2210434ffc8a90daff9cc97e76",
                UserID:                   "meoyyd8za8jdmwfm",
                Username:                 "meoyyd8za8jdmwfm",
                UserPassword:             "38401eb46f8fbb74c1846a5f47f68d83a9bef126b1d4143f886cd464323cdaab",
                UserIP:                   "192.168.0.1",
                LoginURL:                 "http://www.example.com/login",
                UserAuthenticationStatus: "true",
                UserCreationDate:         "2019-08-24T14:15:22Z",
                UserType:                 "VIP",
                MFAPhone:                 "+12081234567",
                MFAEmail:                 "username@example.com",
                UserAgent:                "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
                Context:                  "LOGIN",
        }

        resp := evaluate(client, config.API, payload, token)
        fmt.Printf("%s\n", resp)
}

Login Abuse API Endpoints

The login workflow begins with data collection from the browser application or from the mobile SDK.

Login Abuse endpoint

When the end user logs in with valid credentials, you make a POST to the Login API to get a response with guidance Allow, Block, or Challenge.

Refer to the Login Abuse API help page for more information.

https://api.kount.com/login

Events endpoint

When the end user fails to provide valid credentials, call the Events API with failed attempt details.

When the end user receives a guidance challenge and you have your own multi-factor authentication, then update the outcome of that step up using the Events API.

Refer to the Events API help page for more information.

https://api.kount.com/events

Trusted Device endpoint

A request sent to Kount that creates a trusted device record for the specified user and the device associated with the session.

Refer to the Trusted Device API help page for more information.

https://api.kount.com/trusted-device

Secure MFA endpoint

When you receive a guidance challenge from the Login Abuse API response for an end user and multi-factor authentication (MFA) request is sent to their phone or email, the Secure MFA endpoint is used to check the status of the MFA sent to end user.

Refer to the Secure MFA API help page for more information.

https://api.kount.com/secure-mfa

Account Creation Abuse API Endpoint

The Account Creation Abuse endpoint uses the session ID created by the customer for the Device Data Collector.

Account Creation Abuse endpoint

An account creation request sent to the Account Creation Abuse API that triggers an evaluation of customer-defined policies and returns a guidance Allow, Block, or Challenge based on those policies.

Refer to the Account Creation Abuse API help page for more information.

https://api.kount.com/newaccountopening

Was this article helpful?

0 out of 0 found this helpful