TraitWare Login APIs (OIDC)

Posted on April 24, 2019

TraitWare Login APIs (OIDC) – Client Displayed QR and Email Field

Using the QR Code Directly in the Client Application

To use the TraitWare QR login code directly in your web application client you will need to follow the steps below.  In brief, you will obtain a login string from TraitWare, render it as a QR on your web application client, poll TraitWare to check if the QR has been scanned, and redirect to the redirect URI provided in the response one the QR has been scanned.

Step 1.  Get the loginAttemptUuid to generate a QR Code
Request Type - GET

Endpoint:
https://api.traitware.com/oidc/authorization

Headers {
ContentType : application/json; charset=UTF-8
Accept : application/json
}

Request Query Parameters:
?client_id = xyz123 // from the OIDC application in the TCC
&response_type = code // 'code' is required
&state = abc123 // use state to prevent XSS, the OIDC client should create and verify this

Example:

https://api.traitware.com/oidc/authorization?client_id=59322234&response_type=code&state=abcd1234

Response body - JSON
{
loginAttemptUuid : 6574de4e-84a3-4850-88a7-5839fa900985
loginAttemptSecret : 3131aa4ea5951b593b2d2211c52bdb145bdf04d0
}

The loginAttemptUuid should be rendered into a QR code and displayed for the user to scan.

2. Check the status of the login attempt

To check the status of the login attempt, it is recommended to poll TraitWare every second until you receive a 200 response code or a predetermined timeout is reached.  The loginAttemptUuid will only remain active for 5 minutes.  It is suggested you timeout after 120 seconds and give the user the option to load a new QR.  See the standard TraitWare login as an example.

Request Type - GET

Endpoint:
https://api.traitware.com/customer-api/v1/loginAttempts/{loginAttemptSecret}

Headers
{
ContentType : application/json; charset=UTF-8
Accept: application/json
}

Request body - none

Response body - JSON
{
verification : true // this should only return as true
redirectUri : https://client.example.com/callback
}

redirectURI Query String Parameters:
?code=authorizationCode
&state={state value} // verify at client

HTTP Status 200 indicates login attempt completed. Parse payload for redirectUri.
Note: verification will always be true here, which indicates the QR has been scanned.

HTTP Status 204 indicates login attempt still pending. Continue requests until timeout.

3. Redirect to the redirectUri in the response.

Your OIDC client should handle the response sent to the callback URI to obtain the needed identity of the user logging in. It will use the authorization code to obtain an ID token from TraitWare. That token may be inspected by the OIDC client to obtain information about the user, such as their email address.

Using the Email for Tap-to-Login On Your Web Application

You may optionally want to allow users to log into your application using a Tap-to-Login confirmation.  After submitting their email address, users confirm the login attempt in their pre-authenticated TraitWare mobile.  Note: Users must be logged into their mobile TraitWare app prior to submitting their email address.  This is a security measure to prevent others from attempting users to accepts malicious login attempts.  It is suggested that you make a note below the email field alerting users of the need to authenticate their mobile app first.

Submit the user’s email address to TraitWare

This endpoint relies on the implementation above to obtain a loginAttemptUuid, loginAttemptSecret and a poll to verify if the login attempt has been approved.  Here, the Tap confirmation on the mobile app takes the place of scanning the QR.  A user’s email address is sent to this endpoint after a user enters their email in a field and clicks a button.  They then approve or deny the login attempt on their authenticated mobile app.  If they approve the login attempt, the redirection in Step 3 above will take place automatically, and the user is granted the allowed authorizations.

Request Type - PUT

Endpoint:
https://api.traitware.com/customer-api/v1/loginAttempts/{loginAttemptUuid}

Request Parameters:
{loginAttemptUuid} // the string obtained in Step 1

Headers
{
ContentType: application/json; charset=UTF-8
Accept: application/json
}

Request body
{
loginAttemptUuid // using the string obtained in Step 1 from GET loginAttemptUuid
emailAddress // the email address of the user logging in
}

Response body - none

HTTP Status 204 indicates the email address was successfully submitted.

HTTP Status 401 indicates that the user may not be logged into their TraitWare app. The message returned will be, 'Please log into your TraitWare app before sending your email.'