AuthnResult¶
WingCash returns an AuthnResult from several Direct Authentication API calls. The client should use the content of the AuthnResult to choose which interaction the user should complete next in order to finish signing up or signing in. Not all attributes are present in every interaction.
Initial Attributes¶
These attributes are included in the result of API calls that start a new authentication attempt.
attempt_path
- The path inside the WingCash API for updating or accessing the new authentication attempt. It looks like
/aa/<attempt_id>
. secret
- A string that authenticates the user’s device for the duration of the authentication attempt. The client should not share this string with other devices. In subsequent authentication API calls, the client must set the HTTP Authorization header based on this secret. See WingCash Secret Authentication.
Code Entry Attributes¶
These attributes are provided when the user needs to enter a code sent to them through email, SMS, or another mechanism.
factor_id
- An opaque string that identifies which factor the user should attempt to authenticate. The factor_id changes for each authentication attempt.
code_length
- The length of the code the user should enter. The length is currently either 6 or 9 digits depending on the authentication flow type, but WingCash may expand the code length if necessary.
unauthenticated
- A mapping of the UID strings the user is currently attempting to authenticate. Maps the UID to
original
andcountry
.original
is the UID in a human format, such as a formatted phone number or an email address with capitalization. revealed_codes
- In WingCash development sandboxes and testing environments, this is a list of human-readable strings that reveal the authentication codes sent to the user through email, SMS, or another channel. This allows testers to skip the communication channel. In production, this attribute does not exist.
State Attributes¶
These attributes reveal the progress of the authentication attempt and whether the user has successfully completed authentication.
captcha_required
- A boolean value indicating whether certain sensitive API calls currently require a valid
g-recaptcha-response
field value. WingCash usesg-recaptcha-response
as evidence that a human initiated the API call. authenticated
- A mapping of the UID strings the user has successfully authenticated as part of this authentication attempt. Maps the UID to
original
,country
, andstrong
.original
is the UID in a human format, such as a formatted phone number or an email address with capitalization.strong
is a boolean value indicating whether the authentication mechanism was considered strong. completed_mfa
Boolean: true if the user has authenticated enough factors to complete this authentication attempt. If the user already has a
profile_id
, the AuthnResult will have thetoken
andprofile
attributes listed in the Final Attributes section below.WingCash considers multi-factor authentication complete when the user has authenticated two factors of different types. The possible factor types include email, phone, and device ID. At least one of the factors must use strong authentication in order to authenticate any profile that existed before this authentication attempt. WingCash considers passwords and 9 digit user-entered codes to be strong authentication. 6 digit codes are considered to be weak authentication.
profile_id
- The WingCash profile ID (wallet ID) connected with any authentication factor the user has already authenticated as part of this authentication attempt.
profile_title
- The title of the profile given by
profile_id
. signup
- If this authentication attempt is a
signup
flow, this attribute is an object containingfirst_name
,last_name
,name_checked
(boolean), andhas_password
(boolean).name_checked
is true if the first and last name pass the WingCash name validity tests (such as not containing any Unicode symbols, etc.) This attribute isnull
for other authentication attempt flows. invite_id
- If this authentication attempt is an
accept
flow, this attribute contains the invite ID that started the attempt. Otherwise this attribute isnull
. trust30
- A boolean value indicating whether this authentication attempt will label the client device as trusted once the authentication completes successfully.
Final Attributes¶
Once the user with a wallet completes authentication, the AuthnResult has the following attributes.
token
- An AccessTokenInfo object.
profile
- The ProfileDetail for the newly authenticated user.
Authentication Attempt Decision Tree¶
When your code receives an AuthnResult, you should use code similar to the following to decide what to show the user next:
var next_interaction;
if (!result.completed_mfa) {
if (!result.factor_id && !result.profile_id) {
// Request an authentication factor. The user should input
// an email address or phone number.
next_interaction = 'add-factor';
// After the user interaction, your code should call:
// /aa/(string:id)/add-factor
} else if (result.factor_id) {
// Ask the user to enter a code sent to them by WingCash.
next_interaction = 'enter-code';
// After the user interaction, your code should call:
// /aa/(string:id)/auth-uid
} else {
// Ask the existing user to sign in using their password.
next_interaction = 'sign-in';
// After the user interaction, your code should call:
// /aa/(string:id)/auth-password
}
} else if (!result.profile_id) {
if (result.signup && result.signup.has_password) {
// Ask the user to accept the terms of service and privacy policy.
next_interaction = 'agreement';
// After the user interaction, your code should call:
// /aa/(string:id)/signup-finish
} else if (result.signup && result.signup.name_checked) {
// Ask the user to set a password.
next_interaction = 'set-password';
// After the user interaction, your code should call:
// /aa/(string:id)/set-signup-data
} else {
// Request the user's name.
next_interaction = 'set-personal-name';
// After the user interaction, your code should call:
// /aa/(string:id)/set-signup-data
}
} else {
// The authentication flow is complete.
next_interaction = 'authenticated';
// The access token you need for most WingCash API calls
// is now available as ``result.token.access_token``.
//
// If this is a password reset flow, you should prompt
// the user for a new password and call:
// /aa/(string:id)/reset-password
//
// If the user accepted an invitation, you should call:
// /wallet/finish-invite
}
To optimize the user experience and avoid unnecessary user interactions and server round trips, your code should avoid calling the direct authentication API calls in an unchanging sequence. Ideally, your code should contain an implementation of this decision tree. Your code should be constructed as follows:
- Start an authentication attempt with
POST /aa/signup
,POST /aa/signin
,POST /aa/reset
, orPOST /aa/accept
. Receive an AuthnResult.- Based on the most recent AuthnResult you received, your implementation of the decision tree should decide which interaction to perform with the user. For example, if the
next_interaction
as specified by the tree isenter-code
, you should show a screen or dialog that asks the user to enter a code they received by email or SMS.- At the end of the user interaction, call the API specified by the decision tree comments.
- If the API call succeeds, you will receive an updated AuthnResult; you should then loop back to step 2. If the password was incorrect or some other error occurred, WingCash will respond with an InvalidRequest. You should display the error to the user and repeat the user interaction until it succeeds.