Trust Services API Guide for Service Providers

This document introduces Service Providers to the Trust Services API, which offers additional fraud prevention services to ZenKey mobile security for protecting users and application resources.

ZenKey is an undertaking of the Mobile Authentication Taskforce, which is a joint venture of the four major US wireless carriers. The platform leverages encryption technologies in a user's mobile phone and mobile network, and packages multiple factors of authentication into a streamlined experience for app and website providers. It takes advantage of the unique capabilities and insights of the wireless carriers, and applies an easy and secure way to register, login, and perform other types of authorizations within apps and services. The result for Service Providers is a better user experience and a more secure link to users. ZenKey makes integration easy by following the OpenID Connect (OIDC) authentication protocol.

1.0 Background

Account take over fraud is the leading SIM/wireless fraud attack vector impacting the Financial Services industry. Often this is conducted by a bad actor who swaps a mobile device's SIM card. He or she then calls the mobile carrier's customer service representative and dupes them into believing the SIM was damaged or lost and providing the necessary recovery information to restore service. This might entail moving the victim's phone number from SIM 1 and associating it with the fraudster's SIM 2. The thief then attempts to log into the victim's bank account using the stolen username and password, and faces the bank's challenge for 2nd factor authentication. On success, the bank sends an SMS OTP to the new SIM card. The fraudster enters the 2FA challenge response and successfully logs into the victim's bank account.

The ZenKey platform provides SIM swap protection that presents a stark contrast to the typical fraud outcome. However, for mobile users to benefit from this protection, they must have ZenKey installed on their device and the ZenKey app linked to the Service Provider's app or website.

Whenever a SIM swap occurs on a ZenKey user's mobile device, a recovery flow is triggered, and the user must respond appropriately to regain access to the account. This can be easily performed by legitimate ZenKey users but not as easily by the fraudster who would have to download and install ZenKey, and successfully provide at least 2 out of the following 4 alternate factors of authentication as part of a built-in recovery flow:

  • PIN/biometric
  • Recovery code (setup during ZenKey sign-up)
  • Trusted device (registered during ZenKey sign-up)
  • Carrier username/password

Trust Services was added to ZenKey at the request of several financial institutions who wanted additional API functionality that would enable them to be more proactive in detecting and thwarting fraud by bad actors who have taken control of bank accounts by way of a SIM swap. Trust Services provides a suite of fraud prevention services that sit on top of the ZenKey security platform.

1.1 Overview of Trust Services Fraud Prevention

Trust Services is a collection of different types of APIs and event alerts made available to Service Providers. These will be useful in situations when a Service Provider suspects fraud with their user accounts. Initially, Trust Services will offer these two fraud prevention features (as more are added this document will be updated):

  1. The SIM Tenure Indicator option allows the Service Provider to query carriers via an API call and learn whether the SIM card for a given user has changed within the past 24 hours.
  2. A subscription-based, automated "device change event" alert option provides an immediate message to the Service Provider that is triggered by qualifying mobile user activity.

REMEMBER: The only preconditions for your users to benefit from these added Trust Services is to have ZenKey installed on their mobile device and linked to your app. Users who do not consent to using ZenKey will not be protected!

1.1.1 Different Workflow Options

The Service Provider has the option to:

  • Query a user's SIM Tenure indicator, or
  • Automatically receive alerts about a triggered event indicating that the user's mobile device has changed.

The Service Provider can select the option that matches its fraud prevention objectives, or both options if preferred. The following diagram illustrates the service flows for these two options (blue for API call, green for event alert).

Trust Services 1.0 Service Flows

1.1.2 SIM Tenure Option

By implementing the SIM Tenure option, the Service Provider can at any time perform a SIM check ahead of attempted banking transactions for their selected users.

For example:

  1. A selected user attempts a mobile banking transaction.
  2. Based on the user's carrier ID (MCCMNC), the bank submits a request to the API to verify the user’s carrier information. For example, the following request is sent to the discoveryissuer endpoint.
https://<discoveryissuer-url>/.well-known/openid_configuration?client_id=CLIENT_ID&mccmnc=MCCMNC   
  1. The response includes the endpoint to the user's carrier and the associated openid configuration. For example,
{"issuer":"https://.account.t-mobile.com", "authorization_endpoint":"https://account.t-mobile.com/oauth2/v1/auth", "token_endpoint":"https://brass.account.t-mobile.com/ras/v1/app/token", "jwks_uri":"https://account.t-mobile.com/oauth2/v1/certs", "response_types_supported":["code","token"], "subject_types_supported":["public"], "id_token_signing_alg_values_supported":["RS256"]}
  1. The bank submits an API query to the carrier for the sub-ID for the user. (The Subject Identifier, or subis locally unique and a never-reassigned identifier within the Issuer for the end user.)

POST /v1/usertrait  HTTP/1.1
Host: https://carrier.com
Content-type: application/json
Cache-control: no-cache
x-authorization: <proof-of-possession>


{
“client_id”:”ccid-spapp01”,
“sub”:”mncmcc-xxxxxxxxxxx”,
“usertrait”:”sim_tenure”,
“correlation_id”:”xxxxxxx”
}
  1. The carrier checks the user's SIM tenure indicator.
  2. For the SIM tenure indicator during the last 24 hours, the carrier sends a response to the bank with true, false, or error.

HTTP/1.1 200 OK
Content-type: application/json
{
 "sim_tenure": "true"
}
  1. The bank inputs the sim_tenure API response into its fraud prevention system and schedules whatever action it deems appropriate, such as to accept the transaction, reject it, or put it on hold for further checks.

The following UML (Unified Modeling Language) diagram and script shows the workflow with the associated main actors, roles, actions, artifacts and classes.

SIM Tenure Swimlane Diagram

@startuml sim_tenure_24participant spbox "jv"
participant score as "fraud score"
participant di as "discovery"
participant auditlogs
end boxbox "mno"participant source
participant CCID_IDP
participant usertraitnote over sp,usertrait
   SP has previously authenticated a user
   and tracked their Sub id
end notesp->sp: identify a usersp->di: call discover
di->sp: latest carrier configsp->sp: generate request
sp->sp: sign requestsp->usertrait: query
usertrait ->CCID_IDP: verify sp authentication
usertrait-> CCID_IDP: verify user has consented SP
usertrait-> source: fetch tenure
usertrait-> usertrait: format response
usertrait-> sp: sim_tenure_24:true|falseusertrait -> auditlogs: usertrait log@enduml

1.1.3 Device Change Event Alert Option

An alternative to the Sim Tenure option is the device_change event alert, which can be sent automatically to the bank as notification of a potential SIM event for any of their ZenKey users. This differs from the SIM tenure option in that:

  • The bank does not have to explicitly submit an API call for the SIM tenure.
  • The automatic device_change event alerts the bank that some change has occurred with the device or SIM associated with the given MDN.

For example:

  1. The carrier system detects the SIM swap for the user's phone.

  2. The carrier relays a SIM swap alert to the bank by a set token to the bank's registered event endpoint.

    The following illustrates an event posted by the carrier to the Service Provider's configured event host when the device_change event is triggered.


POST <sp_conifigured> HTTP/1.1
Host: <sp_configured_event_host>
Content-type: application/json
Cache-control: no-cache

{
“set”:” eyJ0eXAiOiJTRVQrSldUIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJ4In0.eyJpc3MiOiJhY2NvdW50LnQtbW9iaWxlLmNvbSIsImlhdCI6MTUwNDYzNTYsImp0aSI6IjMyNGdzaW81NmtsMzI0bW5kZnNsamszMjUiLCJhdWQiOiJjY2lkLW9hdXRocGxheWdyb3VuZDAiLCJzdWIiOiIzMTAyMTMtVTU0NjY0NTM0NS0zNDI1My00NjM0IiwiZXZlbnRzIjpbInNlY3VyaXR5X2V2ZW50Il19.QqPUF5JgiW94eZvGxN4is_-f9PJN9TZpMsQW6ER6giGxWYBmClgCbvQC2FRu534H-5_xhdh1M71QzdV4y7O2amPLF2vVOEhtT3_8wFvsgr3H-wgQ1ScFWWg5wV18HWT-PvweTHOlHG0NLa2Ou0mFDIm6LKsBJJY5E4npPysIVdVFAy_SCUwOPUrYl-7TqipyDpxHilBxKUPMdpZsJzEwLXy21PgQnJwuIm14HpritVTJjm2gW7WwxuJ1kUINWYfy6wkp2umwbHWhYwstYPR78CeDkOKq4mnbwLvlMfy5cHPJ80xpSKXSURDzQ3G9c8Q8WBeOZSQvRXnnCfE_utFaNw
”
}

The SP should reply with a “200 OK” to confirm receipt. If the carrier does not get a “200 OK”, the carrier will retry up to 3 times at 1-minute spacing before recording an error. The carrier caches the combination of (pairwise sub, SP, event, time).

NOTE: The pairwise sub ID for this event should begin with mccmnc-.

If a duplicate event is generated within 60 minutes of a previous (pairwise sub, SP, event), the carrier drops and does not send the duplicate event.

The following is a sample decoded set token.


{type=set+jwt,kid=x}{

“iss”:”account.t-mobile.com”,
                   “iat”:”15046356,
                   “jti”:”324gsio56kl324mndfsljk325”,
                   “aud”:”some_bank_client”,
                   “sub”:”310213-U546645345-34253-4634”,
                   “events”:[“security_event”]
  1. The bank can input this alert into its fraud prevention system and schedule an appropriate action.

The following diagram illustrates the related architecture.

Alert Flow

This option requires:

  • A subscription to the service.
  • SP Event Alert endpoint.
  • Request for "event" scope.

If you subscribe to this service, you will be notified whenever a device_change event has occurred for a connected and consented end user. This is useful to be prepared for subsequent interactions with the identified user. Possible scenarios for the carrier triggering this event include:

  • User has moved their SIM to a new device.
  • User has factory reset their device.
  • User has changed their SIM card.

Each carrier defines a usertraits endpoint in their OpenID configuration. To access this endpoint, you must make a request to the ZenKey Joint Venture via the Service Provider Portal.

By setting the SP Client ID usertraits_enabled parameter, the SP can query for a singular carrier attribute, signal, or indicator. Currently, the only supported attribute is sim_tenure.

NOTE: A user's sim_tenure scope is set to true when an existing SIM is associated with the user's phone number for less than 24 hours.

Each carrier may track a specific event (similar todevice_change) to inform Service Providers that the user’s primary device has changed. For example:

  • User has moved their SIM to a new device (e.g., associating from an IMSI to an IMEI device).

  • User has changed the device's SIM card (e.g., associating a phone number to an IMSI).

    • The carrier may track the association of a phone line to an IMSI. The objective is to track SIM swaps, not phone number changes.

NOTE: A user leaving their SIM in place but asking for a new phone number will be identified as a profile_change and not a device_change, which is a different event alert (not currently included in this offering).

3.0 Getting Started

There are several prerequisites you should complete before implementing the specific MID-Premium service option with ZenKey and your applications:

  • Register with the Service Provider Portal.

  • Ensure your users and MDNs have installed the ZenKey app on their devices.

  • Ensure your app or website has been linked and working with ZenKey.

  • If you will be using the automatic alert option, subscribe to the automatic alert service by visiting the Service Provider Portal.

  • Configure one or more of the following:

    • Events scope access:

    • call_verification_enabled

    • Fraud_score_enabled

  • Configure enum_enabled.

  • Configure contact numbers, such as:

    • 1-800-callme

    • +1-555-666-7777

4.0 Implementation

Once you have set up the prerequisites noted in the "Getting Started" section of this document, configure and test the MID-Premium option you have selected.

4.1 SIM Tenure Option

For the SIM Tenure option, configure the following:

  • User behavior actions to be monitored, such as attempted bank transactions, and/or users/MDNs to be checked for sim_tenure indicator.
  • Process for querying the user's carrier.
  • Process for checking sim_tenure indicator.
  • Process for inputting the sim_tenure indicator into your existing fraud prevention system.
  • User remediation - actions to be implemented for users whose sim_tenure is false.
Test the Option

Use the simulator tool and environment of your choice. Follow these steps to test your implementation:

  1. Swap a mobile phone's SIM card.
  2. Use the phone to connect to your application.
  3. Submit an API query to the carrier for the phone for it's sim_tenure indicator.
  4. Review the response.
  5. Check that the sim_tenure indicator for your phone was input into your test fraud protection system and and remediation actions have been set.

4.2 Device Change Event Alert Option

NOTE: Ensure that you have subscribed to the automatic alert service.

For the Device Change Event Alert option, configure the following:

  • Process for inputting the device_change event into your existing fraud prevention system.
  • User remediation - Associate actions to be performed when a device_change event is received by your fraud detection system.
Test the Option

Use the simulator tool and environment of your choice. Follow these steps to test your implementation:

  1. Add or switch your SIM card to a new device.
  2. Use the phone to connect to your application.
  3. Check that an alert is received from the carrier that identifies the device_change event.
  4. Check that the alert is inserted into your test fraud protection system and and remediation actions have been set.

5.0 Identity Assurance Levels (IAL)

Identity Assurance Levels (IALs) refers both to the strength of data proofing for an individual user’s attributes, or scopes, as well as the process by which recipients of user data are verified. In accordance with National Institute of Standards and Technology (NIST) standards, data proofing includes three confidence levels: high (IAL3), medium (IAL2), and low (IAL1).

This section describes the process for configuring attributes for each IAL. It then explains how a user may consent to certain attributes, depending on their level of proofing, and how certain attributes get assigned to a verification level. Lastly, this section provides a user info response with sample attributes and verification levels.

5.1 Configuring IAL Attributes

The IAL feature is not available to you by default. Only those service providers who have been approved for premium attributes may access IAL. Therefore, to enable IAL you must first receive ZenKey’s permission to request certain attributes from your users. For instance, if you wish to request the government ID attribute from your users and be informed how that data was verified, ZenKey must first grant you approval.

Configuring user attributes is done by logging in to the ZenKey Service Provider Portal. As a prerequisite, you must already have set up your company account. If you have not done so, please keep in mind that your company must be vetted and approved by ZenKey — a process which typically takes 24-48 hours.

With your company account approved, you are now free to set up your project. During this step you may select those end user attributes you would like to request from your users. After you select your attributes, ZenKey will then process this request as well. Only once you receive permission from ZenKey to request those attributes will an updated version of proofing levels be made available to you.

After you request a scope (e.g. email) during the consent flow and the end user approves your request for that scope, because they have already agreed to share that profile information with you, the user would no longer need to provide consent for that attribute again.

Conversely, if a subscriber revokes consent, ZenKey will inform you of this change through the consent_revoked event. To subscribe to this event, visit the ZenKey Service Provider Portal and follow the steps in this guide.

After you subscribe to this event, upon the next authentication request, the user will be required to authorize access to their personal data again. However, do note that a user removing individual scopes will not trigger this event. Only a user removing all scopes will trigger the consent_revoked event.

Because ZenKey does not provide a “silent” user experience (i.e., an implicit flow where the user experience is seamless across a single page) and the prompt parameter is not the same across the different carriers, the user must approve a transaction with each request (referred to as explicit user consent) using the user’s primary device.

5.3 Identity Assurance Level Definitions

Assurance in a subscriber’s identity is described using one of three IALs:

“Low Confidence” — Level 1 (IAL1)

IAL1 means there is no proofing of the attribute. The user attests their personal information is accurate and there is no requirement to link the applicant to a specific real-life identity. Any attributes provided in conjunction with the subject’s activities are self-asserted or should be treated as self-asserted. Self-asserted attributes are neither validated nor verified. For example, if a user edited their name without any identity proofing, then this name would be considered IAL1.

“Medium Confidence” — Level 2 (IAL2)

IAL2 denotes a verified attribute with standard levels of proofing in digital or in-person channels. Evidence supports the real-world existence of the claimed identity and verifies that the applicant is appropriately associated with this real-world identity. IAL2 introduces the need for either remote or physically present identity proofing. For example, if a user provided his or her email, then clicked a link sent to that email address as a method of digital proofing, then this email attribute would be considered IAL2.

“High Confidence” — Level 3 (IAL3)

IAL3 is the strongest proofing method and leaves little room for fraud. Proofing is done by a trained representative in person and normally requires a visit to a retail facility. While some attributes such as phone numbers with AKA authentication are considered IAL3 by themselves, in some cases combining multiple proofing methods can constitute IAL3. For example, digital proofing of a Government ID, when combined with a photo, might hypothetically qualify as IAL3. However, in most instances there will be a human element involved. If the user provides a scanned driver’s license, for instance, this method might then be combined with a verification call to the state DMV in order to confirm there is a valid driver’s license number assigned to that user’s name.

5.4 Attributes and Verification Levels

The table below specifies the attribute names you may request from your users along with their corresponding verification level. Please note that a single attribute can contain more than a single verification level, as verification levels are contingent upon context (e.g. verified email vs. unverified email) and user input (e.g. editing birthdate).

Attribute Verification Level
name IAL2 for postpaid account owner that did a credit check (IAL1 if user has edited name since); IAL2 for digital or retail scan; IAL1 for any user that edits their name, or users without a digital scan after editing.
email IAL2 for emailed link or PIN; IAL1 if email communications start bouncing; IAL1 for edited email addresses that have not yet completed verification.
phone IAL3 for ZenKey authentications as phone just did AKA.
address IAL2 for postpaid primary account holder (owner) pulled from billing address at ZenKey setup; IAL2 if user does driver’s license digital or retail scan; IAL1 for all self-declared addresses (on setup or profile mgmt. edit).
postal_code Attribute pulled from address, and verification is a copy of address’s verification level.
picture IAL1.
location IAL3 when pulled at 9000 ft accuracy. (network reported, not phone queried). NOTE: location is not currently scheduled and is included for reference.
last_4_social IAL2 for postpaid primary account holders where the carrier has done a credit check; IAL1 for all other users, there is no other verification method provided.
birthdate IAL2 for digital scan verified. Carrier can initiate postpaid account owners as IAL2 if the user has not edited since the credit check; IAL1 for unverified or edited value.
is_adult_21 Derived from birthdate and birthdate verification level.
is_adult_18 Derived from birthdate and birthdate verification level.
is_over_13 Derived from birthdate and birthdate verification level.
sim_tenure_24 IAL3 as carriers are the source of truth; IAL1 if carrier’s backend takes more than 1 hr. to reflect SIM swaps.

5.5 Values Returned in User Info Response

When your application is configured for IAL, the user info response will return a verified state parameter whose value contains a number denoting the corresponding attribute level. For example:

  • IAL1: “verified”:1
  • IAL2: “verified”:2
  • IAL3: “verified”:3

In addition to this verified state, the JSON body will also return information about how and when certain attributes were verified, as well as the verified values themselves. For example:

  • Identity document type (e.g. “type”: “drivers_license”)
  • Current value (e.g. “value”:“+13101234567”)
  • Last time used (e.g. last_used_timestamp:“1985-04-12T23:20:50.52Z”)
  • Last verification time (e.g. “last_verified”: “1985-04-12T23:20:50.52Z”)
  • Verification method (e.g. “method”: “inperson|digitalscan”)
Sample JSON Response

Below is a sample JSON response from the userinfo_endpoint for an application with ial_enabled:

    “sub”:“<mccmnc-(salted for this service provider)>”,
    “name”: {
            “value”: “Jane Doe”,
            “given_name”: “Jane”,
            “family_name”: “Doe”,
            “verified”:2},
    “birthdate”: {
            “value”:”0000-03-22”,   //string
            “verified”:1},
    “email”:{
            “value: “janedoe@example.com”,
            “verified”:2},
    “picture”:{
            “value”:https://www.....,
            “verified”:1},
    “address”: {    
             “formatted”:” “1234 Hollywood Blvd.\nLos Angeles, CA 90210-3455”,
             “street_address”: “1234 Hollywood Blvd.\naddress line 2”,
             “locality”: “Los Angeles”,
             “region”: “CA”,
             “postal_code”: “90210-3456”,   
             “country”: “US”,
             “verified”:2},
    “postal_code”: {
            “value”:“90210-3456”,
            “verified”:2},
    “phone”: {
            “value”:“+13101234567”,  //string
            “verified”:3}
    “is_adult18”:{
         “value”:true,
         “verified”,2},
    “is_adult21”:{
          “value”:true,
          “verified”,2},
    “is_over13”:{
        “value”:true,
        “verified”:3},
    “last_4_social”:{
        “value”:“1234”,    //string
        “verified”:2},
    “verification”:{   
        “regulation”:“NIST-SP-800-63a-IAL2”
         “identity_documents”:[{   
                “type”: “drivers_license”,
                “last_verified”: “1985-04-12T23:20:50.52Z”,
                “method”: “inperson|digitalscan”,
                “verified_claims”: “given_name,family_name,birthdate,address”
                },{document2…}]
        }
  }

Note: User info exposed to an application with ial_enabled will differ from a JSON response provided to an application that does not have ial_enabled. Developers are therefore encouraged to write handler code in order to accept both IAL and non-IAL JSON responses.

Support

For technical questions, contact support.

License

Copyright © 2019 ZenKey, LLC.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Revision History

Date Published Document Version ZenKey SDK Version Description
1.31.20 0.0.01 1.0.0 First published version.

Last Update: Document Version 0.0.01, January 30, 2020