Understanding 401 Responses in Jive Connects

Version 1

    As you know if you've used Jive Connects, the first time your application tries to contact a remote server that requires user authentication, it will report back to you the HTTP status 401 error that Connects received back from the remote server.  The typical behavior at this point is for the application to request reconfiguration of user credentials, like this in your callback function:

     

     

    function callback(response) {     if (response.error) {         if (response.error.code == 401) {             osapi.jive.connects.reconfigure("quotes", response, function(feedback) {                 // See discussion below             });         }         else {             // Deal with errors other than 401         }     }     else {         // Process the received data     } } 

     

     

    When the reconfigure() function is called, Jive Connects will challenge the user for credentials (based on the authentication style selected for this service), and then return feedback to the callback function passed to the reconfigure() call.  There are actually four different things that could have happened, so let's discuss what you will see:

     

    User Entered Correct Credentials and Clicked "Approve"

     

    The feedback object sent to the reconfigure callback will include the alias identifying which Jive Connects connection was reconfigured, and there will be no error block:

     

    {   "alias" : "quotes" } 

     

    Typically, the application will retry the request that triggered the 401 response, which will now succeed and the data can be processed as usual.  As long as the credentials for this user remain valid, Jive Connects will transparently include the credentials on each request, and data will flow normally.

     

    User Clicked "Deny"

     

    This indicates that the user declines to provide credentials for this service.  You can tell this happened because the feedback you get back will be different:

     

    {   "alias" : "quotes",   "error" : {     "code" : 401,     "message" : "The user denied this operation."   } } 

     

    What happens next depends on whether the application can proceed without access to this particular service (i.e. usage of the service is optional).  In that case, it should just continue operating, keeping track of the fact that the user refused to provide credentials.

     

    User Closed the Authentication Dialog Popup Without Clicking "Approve" or "Deny"

     

    The feedback is again slightly different, to tell you what happened:

     

    {   "alias" : "quotes",   "error" : {     "code" : 401,     "message" : "The user cancelled this operation"   } }  

     

    What do we do now?  Again, that depends on whether the application absolutely requires this service, or whether it can do something without it.  Generally, the app should treat this case just as if the user had clicked "Deny".

     

    User Entered Incorrect Credentials and Clicked "Approve"

     

    The feedback response in this scenario will be exactly like the case above where the user entered correct credentials and clicked "Approve".

     

    {   "alias" : "quotes" }  

     

    "Huh?" you might ask.  What's going on here?

     

    This feedback makes more sense when we remember exactly what a reconfigure call actually does:

    • Asks the user for credentials (of the appropriate style) for the configured service
    • If the user clicks "Approve", stores those credentials in the Jive database (suitably encrypted, of course).
    • Returns the feedback above to your application.

     

    Jive Connects cannot tell whether the credentials are actually correct or not, because it does not retry the previous request.  This is for two reasons:

    • Whether or not a retry is appropriate is up to the application logic, and Jive Connects has no way to find out what the app wants to do.
    • The previous 401 response (from the remote server) was returned to the app already, and Jive resources associated with that request have already been released (each Jive Connects request stands alone), so Jive no longer has the information it would need to perform a retry even if it knew that a retry was appropriate.

     

    The net effect is that the application is totally in charge of performing requests to the remote server.  In this particular scenario, a retry request will trigger another 401 response (because the credentials are not valid).  A simplistic implementation of "retry on a 401 response until we get something else" will likely annoy your user with repeated requests to reconfigure credentials.  It would be appropriate to keep track of whether you get a 401, do the reconfigure call, and then get a 401 on the retry, so you can provide additional information to the user ... perhaps a message like "It appears that the credentials you just entered are not being recognized by the service.  Would you like to try entering them again?" so that the user can determine whether they want to deal with correcting the credentials now, or do something else with the app first.