Protocols/WebAPI/Auth

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

Desktop clients usually want to authenticate users and obtain security tokens that they can use to access other Services on behalf of the users. A typical example is an desktop instant messaging client trying to authenticate a user and connect to the user's Instant messaging service to send and receive messages.

clientLogin

NINA OpenAuth APIs provide a new method called "clientLogin", to allow clients to authenticate NINA/AIM/ICQ users securely and obtain an authentication token that can be used to access NINA Open Services like WebAIM.

As illustrated in the diagram below, this can be done using NINA OpenAuth Service in 2 steps - authenticate the user using the "clientLogin" request and then make a Service Request on behalf of the user using the security token obtained from the "clientLogin" request.

Steps

Building a Desktop Client using "clientLogin" method involves implementing the following three easy steps:

1. Use "clientLogin" to verify user login credentials and obtain token & session Secret.
2. Using the user's password (collected as part of step 1) as key, generate a hmac_sha256 of the session secret and base64 encode it - we call it SessionKey
   • Session Key = base64_encode[HMAC-SHA256(key, data)] where key is the user's password and data is the session secret obtained from clientLogin response.
   • Please make sure the Session Key string value (base64 encoded value) is properly padded with '=' sign.
   • Example: if a user's password is "test" and the session secret from OpenAuth 'clientLogin' response is "Olpq7NboSbO0gxym", then the Session Key would be base64_encode[HMAC-SHA256("test", "Olpq7NboSbO0gxym")] = "pgBumyiK1xwvjLjcDLRCW7/LySPp+DUXQ3PpDU3c84w="
3. Using the Session Key sign all the Open Services requests (the only services that supports clientLogin tokens at this point are WIM and OpenMail).

The flow diagram below illustrates the above 3 steps:

User Consent

Occasionally some NINA Open Services might want to get the user's consent (permission) to allow your client access the user's data. This involves implementing support for handling 'getConsent' and 'getCaptcha' methods to collect user's consent using a Captcha image and pass the information back to OpenAuth.

Auth API Reference

• clientLogin
• getConsent
• getCaptcha
• getInfo
• logout
• client2Web

Appendix

• Signing Requests