Language

Data Plug can function correctly only if it’s been authorised to access both the 3rd party and individual’s HAT APIs. Furthermore, the service has to maintain valid authentication tokens for both APIs to remain in the “connected” state. As soon as access is lost to either API “disconnected” status should be reported.

Authenticating with HAT

Core plug implementation provides both an interface for user authentication and background services for authentication and authorisation. Plug author can easily customise UI texts, titles, and messaging by modifying conf/messages.en file in their particular plug project. For example, messages.en file for Facebook plug. Alternatively, a completely custom user interface can be set up by implementing your own DataPlugViewSet controller and binding it in the project module.

A more streamlined user authentication experience is also supported. User interface can be skipped altogether if redirecting application adds token=${APP_TOKEN} and redirect=${REDIRECT_URL} query parameters. Here, APP_TOKEN refers to a JWT app token signed by the owner’s HAT for that particular plug and REDIRECT_URL specifies the callback URL to go to after successful setup.

Core plug’s background services also fully automate the caching and refreshing of HAT access tokens to always maintain authenticated state.

Authenticating with 3rd party APIs

Authentication with most of the popular APIs work via OAuth standard. The project uses Silhouette, an authentication library for the Play Framework, simplify the login setup process as much as possible. The library comes with a few default integrations (Facebook, Instagram, etc.), but will require the plug author to implement custom authentication provider for the less popular services. If that’s the case, it will be necessary to create a tweaked authProvider version and supply it to Silhouette instead. The specifics around the required changes will highly depend on the API and cannot be covered in general. We would advise to read the Silhouette documentation, particularly about authentication providers. Also there some examples in the current project repository that can be used for inspiration:

Also, Silhouette-specific configuration parameters have to be included with the project. These can be found in the conf/silhouette.conf file and a particular list of parameters will depend on (1) authentication framework used (examples here), and (2) any custom behaviours added to the default authentication provider. For example, in the Fitbit plug we’ve added authorizationParams, refreshHeaders and customProperties parameters to ensure correct functioning of the auth provider.

fitbit {
   authorizationURL = "https://www.fitbit.com/oauth2/authorize"
   accessTokenURL = "https://api.fitbit.com/oauth2/token"
   redirectURL = "http://dataplug.hat.org:9000/authenticate/fitbit"
   redirectURL = ${?FITBIT_CALLBACK_URL}
   refreshURL = "https://api.fitbit.com/oauth2/token"
   clientID = ""
   clientID = ${?FITBIT_CLIENT_ID}
   clientSecret = ""
   clientSecret = ${?FITBIT_CLIENT_SECRET}
   scope = "activity heartrate location profile sleep weight"
   authorizationParams {
     response_type = "code"
   }
   refreshHeaders {
     Content-Type = "application/x-www-form-urlencoded"
   }
   customProperties {
     authorization_header_prefix = "Basic"
     parameters_location = "query"
   }
 }