Protocols/WebAPI/Auth/WebApp

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

The NINA Open Authentication API (OpenAuth) empowers third-party web sites and applications to authenticate NINA and AIM users through their Web Sites/Applications. An AIM/NINA/ICQ user can now log into a third-party Web Site/Application and seamlessly access NINA Open web services or new services built on top of NINA services. Using the NINA Open Authentication API, external Web Sites/Applications can call NINA's Secure Login Page and get an Authentication Token. Upon user's permission via NINA's Secure Consent Page, they can even use the Authentication Token to access NINA/AIM Open Web Services on behalf of the user.

In the typical usage illustrated below, the AIM/NINA member successfully accesses his/her Buddy List directly through the external site once all the appropriate handshakes and validations have occurred between the user, the external site, OpenAuth API, and NINA's backend. In other words, now third-party implementations can securely offer cool new applications and services to a vastly expanded base of users.

Note: Steps 6 - 10 only occur once per session or once per user based on user's permission choice (Grant once or always).

Enabling Authentication on a Web Site using NINA OpenAuth API involves implementing the following easy steps:

1. Redirecting the user to OpenAuth "login" url with appropriate required parameters
2. Handling the response redirect from OpenAuth "login" to receive Authentication token and process error codes as required
3. Making NINA Open Service requests along with the Authentication token obtained from "login"
   • Optionally, using OpenAuth "getInfo" method to validate token and retrieve user's information.

Enabling Authentication for a browser based App (Web 2.0/AJAX Model) involves implementing the following easy steps:

1. Sending an Asynchronous call to OpenAuth's "getToken" method to retrieve Authentication token if a user is already signed in. The "getToken" request can be made as a JSONP call from the browser side.
2. If the user is not already logged in, redirect the user to OpenAuth "login" page in one of the three following ways:
   1. Redirect to OpenAuth "login" url with required parameters
   2. Redirect to OpenAuth "login" url with required parameters in an IFRAME with no "succUrl" parameter (please refer to appendix for a list of URL Fragments used to notify Authentication status)
   3. Redirect to OpenAuth "login" url with required parameters in a new browser window
3. Handling the response from OpenAuth getToken/login methods to receive Authentication token and process error codes as required
4. Making NINA Open Service requests along with the Authentication token obtained from "login"
   • Optionally, using OpenAuth "getInfo" method to validate token and retrieve user's information.

Auth API Reference

• login
• getToken
• getInfo
• logout

Appendix

When "login" and "consent" (returned when a Site tries to access NINA Services on behalf of the user) urls are invoked in IFRAMEs (without "succUrl" param) instead of the standard full browser redirects (with "succUrl" param), the following values are set as URL Fragments to notify the Web Site/Application about the user's flow status:

  1. AUTHCANCEL - user canceled login flow (user clicked on cancel button)
  2. AUTHDONE - user successfully authenticated
  3. INVALIDCALLBACK - invalid jsonp callback ('c' param) value
  4. CONSENTINVALIDTOKEN - consent url called with invalid token (expired/corrupted/replayed/invalid usage)
  5. CONSENTDONE - consent process done (user clicked on Allow Always or Allow this time only buttons)
  6. CONSENTCANCEL - user denied permission