Get User Identity and Trust

Every time your users login using BindID, you receive user metadata containing their user identity and trust profile. BindID maintains a trust profile for each user and their devices—such as when the user was first or last seen by you or by any provider integrated with BindID. The user metadata can be obtained from the ID token or UserInfo using backend OIDC APIs, as described below.

Get ID and Access Tokens

For each successful authentication, the BindID SDK returns an authorization code, which you can exchange for ID and access tokens. The ID token contains the user metadata, as well as trust indicators for the device and authenticator used in the authentication session. The access token can be used in various other API requests, such as to report and retrieve data for the authenticated user.

To get an ID and access token, send a HTTP POST request to the OIDC /token endpoint. The request body should include the authorization code returned by the SDK, the redirect URI you passed in the authentication request, and your client credentials. See the Token API reference.

For example:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fyour-rp.example.org&client_id=qL4IJvJ1kHwunrLNOGhAAVCMD39EDPWF&client_secret=123

The /token response includes the ID token in the id_token field, which you can decode to obtain the user metadata.

For example:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "hjg2khf236ghf",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "aof ... dfhsf.ksd ... KJhsKJD.lkasjd ... hnsdc"
}

Note: The client should resolve the authorization code and exchange tokens at the backend; backend systems must not assume tokens received from the client are valid without validating them—including the intended audience and nonce (see Validate ID Tokens).

Get User Information

You can also obtain the user metadata from the OIDC /userinfo endpoint, for example, if required for your OIDC implementation. Send an HTTP GET or POST request to the OIDC /userinfo endpoint. The Authorization header should include the access token returned in the /token response in the access_token field. See the UserInfo API reference.

For example:

GET /userinfo HTTP/1.1
Authorization: Bearer f3uv87HG87
Host: signin.bindid-sandbox.io

The /userinfo response includes the user metadata directly in the body.

For example:

HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "123e4567-e89b-12d3-a456-426652340000",
"auth_time": 1605180698,
"nonce": "n-077-RsA2Kh",
"acr": "ts.bindid.iac.email ts.bindid.iac.phone_number",
"amr": ["ts.bind_id.ama", "ts.bind_id.mfca"],
"bindid_alias": "username@domain",
"email": "user@acme.com",
"email_verified": true,
"phone_number": "+12125556789",
"phone_number_verified": true,
"bindid_info": {
"capp_first_login_from_authenticating_device": 1605180500,
"authenticating_device": {
"browser_type": "Mobile",
"os_type": "iOS",
"os_version": "14.1",
"browser_version": "Safari"
},
"capp_last_login_from_authenticating_device": 1605180574,
"capp_last_login": 1605180577,
"capp_first_login": 1605180504,
"capp_first_confirmed_login": 1605180577,
"originating_device": {
"browser_type": "Chrome",
"os_type": "Mac OS",
"os_version": "10.15.7",
"browser_version": "86.0.4240.183"
}
},
"bindid_network_info": {
"user_registration_time": 1605180498,
"authenticating_device_registration_time": 1605180500,
"authenticating_device_last_seen": 1605180691,
"user_last_seen": 1605180694,
"confirmed_capp_count": 1,
"device_count": 2
}
}

Handle User Token

The user metadata may correspond to a user that's already known to BindID or a new user:

  • If the user is unknown to BindID, the ID token (and UserInfo response) will not include the bindid_alias claim. The application should respond by taking the user through a registration process where the application establishes user identity (see Send Session Feedback). Afterwards, the application should set a BindID alias for the user so that subsequent logins will be associated with it.
  • If the user is known to BindID, the ID token (and UserInfo Response) will include the bindid_alias claim. Your application should look up this value within its user-store to identify the application user to which this alias is registered, and use that user for the rest of the session.