Request Authorization

Once the BindID SDK is initialized, you can invoke a BindID authentication process in two ways—either programmatically, or by specifying an HTML element that will invoke authentication in response to click events.

Using HTML Elements

To request authorization using HTML elements:

Add an HTML element with CSS class xm-bind-id-button, and the attributes below assigned to it. When the element will process the click event, the authentication process will be initiated.

Attribute NameDescription
data-xm-bind-id-on-failureName of the function you create to handle the OIDC authorization failure result. This function receives an error.
data-xm-bind-id-on-successName of the function you create to handle the OIDC authorization success result. This function isn’t invoked in this version of the SDK (page will redirect if successful).

Here’s an example of a BindID button:

<button class='xm-bind-id-button' data-xm-bind-id-on-success="onSuccess" data-xm-bind-id-on-failure="onFailure">
Biometric Login</button>

In addition, add the following set of meta tags to the page before the script tag used to load the SDK:

Meta NameDescription
xm-bind-id-redirect_uriURI to which the user-agent will be redirected when the authentication process is completed (which must correspond to one of the allowed URIs configured in the BindID Admin Portal). Redirection will occur as per the OIDC standard. Equivalent to the redirectUri parameter of the authenticate() SDK call.
xm-bind-id-nonceOptional. Nonce value for the authorization request (as per the OIDC standard). This value will be included in the ID token minted by BindID (see API Reference). Equivalent to the nonce parameter of the authenticate() SDK call.
xm-bind-id-stateOptional. State value for the authorization request (as per the OIDC standard), which will be included in the authorization response sent to the client. Unless disabled, the SDK will verify that the state parameter in the authorization response is identical to the one sent in the request. Equivalent to the state parameter of the authenticate() SDK call.
xm-bind-id-scopeOptional. Set of scopes that will include additional information in the ID Token Claims. Users will be asked for the relevant consent. Available options: bindid_network_info, email, and phone. Equivalent to the scope parameter of the authenticate() SDK call.
xm-bind-id-verificationsOptional. Set of data verifications to request for the user, such as verified phone number (e.g., using SMS OTP). Available options: phone and email. Equivalent to the verifications parameter of the authenticate() SDK call.
xm-bind-id-custom_messageOptional. Custom message to present on the consent screens, which provides details for the authentication context. Equivalent to the customMessage parameter of the authenticate() SDK call.
xm-bind-id-aux_linkOptional. A URL target for the custom option link presented on the Computer-to-Mobile Options screen, whose prefix must correspond to the one configured in the BindID Admin Portal, and which must begin with https:// and end with /. If not provided, no link will be displayed. Equivalent to url of otherLoginOptions parameter of the authenticate() SDK call.
xm-bind-id-aux_link_titleOptional. Title for the custom option link presented on the Computer-to-Mobile Options screen. Equivalent to title of otherLoginOptions parameter of the authenticate() SDK call.

For example:

<meta name="xm-bind-id-redirect_uri" content="https://your-rp.example.com">
<meta name="xm-bind-id-nonce" content="12345">
<meta name="xm-bind-id-state" content="demo_state">
<meta name="xm-bind-id-scope" content="bindid_network_info">
<meta name="xm-bind-id-verifications" content="phone email">
<meta name="xm-bind-id-custom_message" content="Login using Your RP">
<meta name="xm-bind-id-aux_link" content="https://your-rp.example.com/more">
<meta name="xm-bind-id-aux_link_title" content="More ways to verify">

Using SDK Calls

To request authorization programatically:

Invoke the authenticate() SDK method (see the API reference). This will redirect if successful; otherwise, it will fail. Here’s an example of invoking the authenticate() SDK method—where phone and email is requested, phone and email verification is requested, a link is presented in the Computer-to-Mobile Options screen, and custom text is defined for the consent screens:

function invokeBindId() {
window.XmBindId.authenticate({
redirectUri: 'https://your-rp.example.com',
scope: [window.XmBindId.XmBindIdScopeType.Phone,window.XmBindId.XmBindIdScopeType.Email],
verifications: [window.XmBindId.XmRequiredVerifications.Phone, window.XmBindId.XmRequiredVerifications.Email],
otherLoginOptions: {
title: 'More ways to verify',
url: 'https://your-rp.example.com/more'
},
customMessage: 'Login using Your RP'
}).then(res => {
onSuccess(res);
}, err => {
onFailure(err);
})
}