Home / IBM Verify SDK for Javascript / Ibm Verify Sdk Object Model / AuthenticatorContext

AuthenticatorContext

AuthenticatorContext is used for interacting with the IBM Verify mobile app.

Function	Parameters	Async	Return
AuthenticatorContext	oauth	🚫	AuthenticatorContext
authenticators	token	✅	Object
initiateAuthenticator	dataObj, token	✅	Object
createVerification	authenticatorId, formData, token	✅	Object
viewVerifications	authenticatorId, token	✅	Object
viewVerification	authenticatorId, transactionId, token	✅	Object
pollVerification	authenticatorId, transactionId, token, delay, attempts	✅	Object
enabled	authenticatorId, enabled, token	✅	Object
deleteAuthenticator	authenticatorId, token	✅	Object
methodEnabled	id, enabled, token	✅	Object
methods	authenticatorId, token	✅	Object

Note: The token parameter is not required when using Implicit Flow. For Authorization Code Flow (AZN) associating a request to the correct token is up to the developer, in the samples the function getRequestersToken() is used.

AuthenticatorContext(oauth)

The constructor, requires an OauthContext object as a parameter and returns an AuthenticatorContext object.

Sample code:

let authClient = OAuthContext(config);
let authCtx    = AuthenticatorContext(authClient);

let authClient = OAuthContext(config);
let authCtx    = AuthenticatorContext(authClient);

let authClient = OAuthContext(config);
let authCtx    = AuthenticatorContext(authClient);

authenticators(token)

Returns an object with the property authenticators where the value is an array of authenticator objects which are registered to the user.

Sample code:

app.get('/authenticators', (req, res) => {
    
    // retrieve the requesters associated token
    let token = getRequestersToken(req);

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.authenticators(token).then(response => {
        res.send(JSON.stringify(response.response));
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

authCtx.authenticators().then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

authCtx.authenticators().then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

Sample response

{
  "authenticators": [
    {
      "creationTime": "2018-04-19T09:21:38.414Z",
      "enabled"     : true,
      "clientId"    : "64f20377-6041-47ec-a47f-d9bd0a5095e7",
      "state"       : "ACTIVE",
      "owner"       : "50TPV1B8Q9",
      "attributes"  : {
        "deviceName"        : "John's iPhone",
        "pushToken"         : "5fw75HqyXnivkpmb%3AudWNSI7s",
        "fingerprintSupport": true,
        "applicationVersion": "1.0.5",
        "faceSupport"       : false,
        "accountName"       : "Savings Account",
        "deviceType"        : "iPhone",
        "deviceId"          : "3f9821f4-b79f-47e3-9efc-51a48cf00ea7",
        "frontCameraSupport": true,
        "osVersion"         : "11.2.1",
        "applicationId"     : "com.ibm.security.verifyapp",
        "platformType"      : "IOS",
        "verifySdkVersion"  : "1.0.1"
      },
      "id": "7b676daa-8725-472d-a7f2-88f05c0b798b"
    }
  ]
}

initiateAuthenticator(dataObj, token)

NOTE: registrationProfileId must be set in the OAuthContext config

Initiates an authenticator registration, the response contains a base64 encoded png QR code which can be scanned using the IBM Verify mobile app to complete the registration.

Sample code:

app.post('/authenticators/initiation', (req, res) => {
    
    // retrieve the requesters associated token
    let token = getRequestersToken(req);

    let dataObj = {
        accountName: req.body.accountName // optional
    }

    authCtx.initiateAuthenticator(dataObj, token).then(response => {
        res.send(response.response.qrcode);
    }).catch(error => {
        // set the correct header
        res.setHeader("Content-Type", "application/json");
        res.send(JSON.stringify(error));
    });
})

let dataObject = {
    accountName: 'Example' // optional
}

authCtx.initiateAuthenticator(dataObj, token).then(response => {
    let QR = response.qrcode;
    console.log(QR);
    
    // display the QR code
    document.body.innerHTML += `<img src="data:image/png;base64, ${QR}"/>`;
}).catch(error => {
    console.log(JSON.stringify(error));
});

let dataObject = {
    accountName: 'Example' // optional
}

authCtx.initiateAuthenticator(dataObj, token).then(response => {
    let QR = response.qrcode;
    console.log(QR);
    
    // display the QR code
    document.body.innerHTML += `<img src="data:image/png;base64, ${QR}"/>`;
}).catch(error => {
    console.log(JSON.stringify(error));
});

Sample response

{
  "code"   : "rNxkpy2TSdv3pFgVW9kq",
  "qrcode" : "c2FtcGxlCg==",
  "version": {
    "platform": "com.ibm.security.access.verify",
    "number"  : "1.0.1"
  },
  "registrationUri": "https://tenant.ice.ibmcloud.com/v1.0/authenticators/registration",
  "accountName"    : "Savings Account"
}

createVerification(authenticatorId, formData, token)

Sends a verification to the given authenticator with the supplied data.

The response includes a property id, this can be used to poll for the verification's state change using viewVerification()

Sample code:

app.post('/verification/create', (req, res) => {
    
    // retrieve the requesters associated token
    let token           = getRequestersToken(req);
    let authenticatorId = req.body.authenticatorId;

    let formData = {
        methodId        : req.body.methodId,
        send            : req.body.send,
        txMessage       : req.body.txMessage,         // optional
        originIpAddress : req.body.originIpAddress,   // optional
        originUserAgent : req.body.originUserAgent,   // optional
        txAdditionalData: req.body.additionalData,    // optional
        title           : req.body.title,             // optional
        pushMessage     : req.body.pushMessage,       // optional
        expires         : req.body.expires            // optional
    }

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.createVerification(authenticatorId, formData, token).then(response => {
        res.send(JSON.stringify(response.response));
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

let formData = {
    methodId        : methodId,
    send            : true,
    txMessage       : 'example',         // optional
    originIpAddress : originIpAddress,   // optional
    originUserAgent : originUserAgent,   // optional
    txAdditionalData: {foo: 'bar'},      // optional
    title           : 'example',         // optional
    pushMessage     : 'example',         // optional
    expires         : 30                 // optional
}
authCtx.createVerification(authenticatorId, formData).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

let formData = {
    methodId        : methodId,
    send            : true,
    txMessage       : 'example',         // optional
    originIpAddress : originIpAddress,   // optional
    originUserAgent : originUserAgent,   // optional
    txAdditionalData: {foo: 'bar'},      // optional
    title           : 'example',         // optional
    pushMessage     : 'example',         // optional
    expires         : 30                 // optional
}
authCtx.createVerification(authenticatorId, formData).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

Sample response

{
  "creationTime": "2018-04-19T09:21:38.414Z",
  "authenticationMethods": [
    {
      "methodType"    : "signature",
      "additionalData": [
        {
          "name" : "foo",
          "value": "bar"
        }
      ],
      "id"     : "f867dceb-a360-44f4-883f-70723272d27f",
      "subType": "fingerprint"
    }
  ],
  "expiryTime": "2018-04-19T09:21:38.414Z",
  "userActions": [
    {
      "userAction": "VERIFY_ATTEMPT",
      "signedData": "563r324F3214==",
      "id"        : "f867dceb-a360-44f4-883f-70723272d27f"
    }
  ],
  "transactionData" : "{\\\"originIpAddress\\\":\\\"192.168.222.222\\\",\\\"originUserAgent\\\":\\\"Mozilla Firefox 11\\\",\\\"additionalData\\\":[{\\\"name\\\":\\\"foo\\\",\\\"value\\\":\\\"bar\\\"}],\\\"message\\\":\\\"There is an action that needs your attention.\\\",\\\"timestamp\\\":\\\"2018-04-19T09:21:38.414Z\\\"}",
  "authenticatorId" : "7b676daa-8725-472d-a7f2-88f05c0b798b",
  "state"           : "PENDING",
  "completionTime"  : "2018-04-19T09:21:38.414Z",
  "transactionUri"  : "https://tenant.ice.ibmcloud.com/v1.0/authenticators/{id}/verification/{trxnId}",
  "logic"           : "OR",
  "owner"           : "50TPV1B8Q9",
  "pushNotification": {
    "pushToken"     : "5fw75HqyXnivkpmb%3AudWNSI7s",
    "title"         : "IBM Verify",
    "send"          : true,
    "completionTime": "2018-04-19T09:21:38.414Z",
    "startTime"     : "2018-04-19T09:21:38.414Z",
    "sendState"     : "SENDING",
    "message"       : "You have a pending authentication challenge"
  },
  "id": "a5f562cb-684b-4918-bca6-def6f6c4a81b"
}

viewVerifications(authenticatorId, token)

Returns all of the verifications for the given authenticator.

Sample code:

app.get('/verifications/:authenticatorId', (req, res) => {
    
    // retrieve the requesters associated token
    let token           = getRequestersToken(req);
    let authenticatorId = req.params.authenticatorId;

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.viewVerifications(authenticatorId, token).then(response => {
        res.send(JSON.stringify(response.response));
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

authCtx.viewVerifications(authenticatorId).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

authCtx.viewVerifications(authenticatorId).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

Sample response

{
  "verifications": [
    {
      "creationTime"         : "2018-04-19T09:21:38.414Z",
      "authenticationMethods": [
        {
          "methodType"    : "signature",
          "additionalData": [
            {
              "name" : "foo",
              "value": "bar"
            }
          ],
          "id"     : "f867dceb-a360-44f4-883f-70723272d27f",
          "subType": "fingerprint"
        }
      ],
      "expiryTime" : "2018-04-19T09:21:38.414Z",
      "userActions": [
        {
          "userAction": "VERIFY_ATTEMPT",
          "signedData": "563r324F3214==",
          "id"        : "f867dceb-a360-44f4-883f-70723272d27f"
        }
      ],
      "transactionData" : "{\\\"originIpAddress\\\":\\\"192.168.222.222\\\",\\\"originUserAgent\\\":\\\"Mozilla Firefox 11\\\",\\\"additionalData\\\":[{\\\"name\\\":\\\"foo\\\",\\\"value\\\":\\\"bar\\\"}],\\\"message\\\":\\\"There is an action that needs your attention.\\\",\\\"timestamp\\\":\\\"2018-04-19T09:21:38.414Z\\\"}",
      "authenticatorId" : "7b676daa-8725-472d-a7f2-88f05c0b798b",
      "state"           : "PENDING",
      "completionTime"  : "2018-04-19T09:21:38.414Z",
      "transactionUri"  : "https://tenant.ice.ibmcloud.com/v1.0/authenticators/{id}/verification/{trxnId}",
      "logic"           : "OR",
      "owner"           : "50TPV1B8Q9",
      "pushNotification": {
        "pushToken"     : "5fw75HqyXnivkpmb%3AudWNSI7s",
        "title"         : "IBM Verify",
        "send"          : true,
        "completionTime": "2018-04-19T09:21:38.414Z",
        "startTime"     : "2018-04-19T09:21:38.414Z",
        "sendState"     : "SENDING",
        "message"       : "You have a pending authentication challenge"
      },
      "id": "a5f562cb-684b-4918-bca6-def6f6c4a81b"
    }
  ]
}

viewVerification(authenticatorId, transactionId, token)

Returns a specific verification.

Sample code:

app.post('/verification/:authenticatorId/:transactionId', (req, res) => {
    
    // retrieve the requesters associated token
    let token           = getRequestersToken(req);
    let authenticatorId = req.params.authenticatorId;
    let transactionId   = req.params.transactionId;

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.viewVerification(authenticatorId, transactionId, token).then(response => {
        res.send(JSON.stringify(response.response));
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

authCtx.viewVerification(authenticatorId, transactionId).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

authCtx.viewVerification(authenticatorId, transactionId).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

Sample response

{
  "creationTime"         : "2018-04-19T09:21:38.414Z",
  "authenticationMethods": [
    {
      "methodType"    : "signature",
      "additionalData": [
        {
          "name" : "foo",
          "value": "bar"
        }
      ],
      "id"     : "f867dceb-a360-44f4-883f-70723272d27f",
      "subType": "fingerprint"
    }
  ],
  "expiryTime" : "2018-04-19T09:21:38.414Z",
  "userActions": [
    {
      "userAction": "VERIFY_ATTEMPT",
      "signedData": "563r324F3214==",
      "id"        : "f867dceb-a360-44f4-883f-70723272d27f"
    }
  ],
  "transactionData" : "{\\\"originIpAddress\\\":\\\"192.168.222.222\\\",\\\"originUserAgent\\\":\\\"Mozilla Firefox 11\\\",\\\"additionalData\\\":[{\\\"name\\\":\\\"foo\\\",\\\"value\\\":\\\"bar\\\"}],\\\"message\\\":\\\"There is an action that needs your attention.\\\",\\\"timestamp\\\":\\\"2018-04-19T09:21:38.414Z\\\"}",
  "authenticatorId" : "7b676daa-8725-472d-a7f2-88f05c0b798b",
  "state"           : "PENDING",
  "completionTime"  : "2018-04-19T09:21:38.414Z",
  "transactionUri"  : "https://tenant.ice.ibmcloud.com/v1.0/authenticators/{id}/verification/{trxnId}",
  "logic"           : "OR",
  "owner"           : "50TPV1B8Q9",
  "pushNotification": {
    "pushToken"     : "5fw75HqyXnivkpmb%3AudWNSI7s",
    "title"         : "IBM Verify",
    "send"          : true,
    "completionTime": "2018-04-19T09:21:38.414Z",
    "startTime"     : "2018-04-19T09:21:38.414Z",
    "sendState"     : "SENDING",
    "message"       : "You have a pending authentication challenge"
  },
  "id": "a5f562cb-684b-4918-bca6-def6f6c4a81b"
}

pollVerification(authenticatorId, transactionId, token, delay, attempts)

Polls a specific verification for a state change. The initial state of the verification is 'PENDING' / 'SENDING' when this is updated i.e. the user responds to the push notification through the IBM Verify mobile app. The current state is returned.

Both the delay between polls and the number of polling attempts are provided as arguments.

Sample code:

app.post('/verification/:authenticatorId/:transactionId', (req, res) => {
    
    // retrieve the requesters associated token
    let token           = getRequestersToken(req);
    let authenticatorId = req.params.authenticatorId;
    let transactionId   = req.params.transactionId;

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.pollVerification(authenticatorId, transactionId, token, 1000, 60).then(response => {
        res.send(JSON.stringify(response.state));
        // response.token will be null unless a token refresh occurred 
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

Not supported in Vanilla JS

Not supported in React JS

enabled(authenticatorId, enabled, token)

Updates the enabled state (boolean) for the given authenticator.

Sample code:

app.patch('/authenticator/enabled', (req, res) => {
    
    // retrieve the requesters associated token
    let token           = getRequestersToken(req);
    let enabled         = req.body.enabled;
    let authenticatorId = req.body.authenticatorId;

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.enabled(authenticatorId, enabled, token).then(response => {
        res.send(JSON.stringify({authenticatorId: authenticatorId, enabled:enabled}));
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

authCtx.enabled(authenticatorId, enabled).then(response => {
    console.log(JSON.stringify({authenticatorId: authenticatorId, enabled:enabled}));
}).catch(error => {
    console.log(JSON.stringify(error));
});

authCtx.enabled(authenticatorId, enabled).then(response => {
    console.log(JSON.stringify({authenticatorId: authenticatorId, enabled:enabled}));
}).catch(error => {
    console.log(JSON.stringify(error));
});

deleteAuthenticator(authenticatorId, token)

Deletes the given authenticator.

Sample code:

app.delete('/authenticators/:authenticatorId', (req, res) => {
    
    // retrieve the requesters associated token
    let token            = getRequestersToken(req);
    let authenticatordId = req.params.authenticatorId;

    authCtx.deleteAuthenticator(authenticatorId, token).then(response => {
        res.send(`Authenticator: ${authenticatorId} has been deleted`);
    }).catch(error => {
        // set the correct header
        res.setHeader("Content-Type", "application/json");
        res.send(JSON.stringify(error));
    });
})

authCtx.deleteAuthenticator(authenticatorId).then(response => {
    console.log(`Authenticator: ${authenticatorId} has been deleted`);
}).catch(error => {
    // set the correct header
    res.setHeader("Content-Type", "application/json");
    console.log(JSON.stringify(error));
});

authCtx.deleteAuthenticator(authenticatorId).then(response => {
    console.log(`Authenticator: ${authenticatorId} has been deleted`);
}).catch(error => {
    // set the correct header
    res.setHeader("Content-Type", "application/json");
    console.log(JSON.stringify(error));
});

methodEnabled(id, enabled, token)

Updates the enabled state (boolean) for the given method.

Sample code:

app.patch('/method/enabled', (req, res) => {
    
    // retrieve the requesters associated token
    let token    = getRequestersToken(req);
    let enabled  = req.body.enabled;
    let methodId = req.body.methodId;

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.methodEnabled(methodId, enabled, token).then(response => {
        res.send(JSON.stringify({methodId: methodId, enabled:enabled}));
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

let enabled = false;

authCtx.methodEnabled(methodId, enabled).then(response => {
    console.log(JSON.stringify({methodId: methodId, enabled:enabled}));
}).catch(error => {
    console.log(JSON.stringify(error));
});

let enabled = false;

authCtx.methodEnabled(methodId, enabled).then(response => {
    console.log(JSON.stringify({methodId: methodId, enabled:enabled}));
}).catch(error => {
    console.log(JSON.stringify(error));
});

methods(authenticatorId, token)

Returns all of the methods for the given authenticator.

Sample code:

app.get('/methods/:authenticatorId', (req, res) => {
    
    // retrieve the requesters associated token
    let token           = getRequestersToken(req);
    let authenticatorId = req.params.authenticatorId;

    // set the correct header
    res.setHeader("Content-Type", "application/json");

    authCtx.methods(authenticatorId, token).then(response => {
        res.send(JSON.stringify(response.response));
    }).catch(error => {
        res.send(JSON.stringify(error));
    });
})

authCtx.methods(authenticatorId).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

authCtx.methods(authenticatorId).then(response => {
    console.log(JSON.stringify(response));
}).catch(error => {
    console.log(JSON.stringify(error));
});

Sample response

{
  "signatures": [
    {
      "enrollmentUri": "https://tenant.ice.ibmcloud.com/v1.0/authnmethods/signature/{id}",
      "_embedded"    : {
        "creationTime": "2018-04-19T09:21:38.414Z",
        "enabled"     : true,
        "clientId"    : "64f20377-6041-47ec-a47f-d9bd0a5095e7",
        "state"       : "ACTIVE",
        "owner"       : "50TPV1B8Q9",
        "attributes"  : {
          "deviceName"        : "John's iPhone",
          "pushToken"         : "5fw75HqyXnivkpmb%3AudWNSI7s",
          "fingerprintSupport": true,
          "applicationVersion": "1.0.5",
          "faceSupport"       : false,
          "accountName"       : "Savings Account",
          "deviceType"        : "iPhone",
          "deviceId"          : "3f9821f4-b79f-47e3-9efc-51a48cf00ea7",
          "frontCameraSupport": true,
          "osVersion"         : "11.2.1",
          "applicationId"     : "com.ibm.security.verifyapp",
          "platformType"      : "IOS",
          "verifySdkVersion"  : "1.0.1"
        },
        "id": "7b676daa-8725-472d-a7f2-88f05c0b798b"
      },
      "creationTime": "2018-04-19T09:21:38.414Z",
      "enabled"     : false,
      "subType"     : "fingerprint",
      "attributes"  : {
        "authenticatorId" : "7b676daa-8725-472d-a7f2-88f05c0b798b",
        "deviceSecurity"  : true,
        "authenticatorUri": "https://tenant.ice.ibmcloud.com/v1.0/authenticators/{id}",
        "algorithm"       : "RSASHA256",
        "additionalData"  : [
          {
            "name" : "foo",
            "value": "bar"
          }
        ]
      },
      "owner"     : "50TPV1B8Q9",
      "methodType": "signature",
      "validated" : false,
      "id"        : "f867dceb-a360-44f4-883f-70723272d27f"
    }
  ]
}