Developer Blog

Connect IQ 2: Authentication

08/04/16 @ 04:51 PM

throws StringNotTautException

Today there are countless web services available to developers, but up until now most have been inaccessible to Connect IQ developers. The reason is that these services use either OAUTH 1 or 2 to provide access control, and this functionality did not exist in Connect IQ. Biker Monkey adds new OAUTH APIs into the Communications module that allow widgets and device apps to make authenticated calls. We’ve also added this feature into Aikido monkey, so you can use this in your 1.x apps as well.

OAUTH 101

OAUTH provides a standard way for developers to authenticate to gain access to web APIs. Before an app can access the web API, the developer must register the app with the service. During registration you must provide a redirect URL that will be used to retrieve the credentials. Once registered the app will provide a client id and secret, which are necessary for the login process.

OAUTH Flow

To access the web service, the app must authenticate the user. To do this, the app redirects the user’s web browser to the web service authentication page, providing the secret, the client id, and the redirect URL. After the service has authenticated the user, it redirects their browser back to the client providing an access token. The access token can then be used in subsequent calls to the web service.

OAUTH and Wearables

The OAUTH standard is based on the world of web browsers and mobile applications, but in general people don’t want to enter their username and password on their watch. Connect IQ has added some new APIs to allow you to write OAUTH enabled apps:

    //! Request an OAuth sign-in on Garmin Connect Mobile. A notification will trigger on the phone, that when clicked,
    //! provides a webview that shows initialUrl. If the user grants permission to the app the function given to
    //! registerForOAuthMessages() will be called with a Dictionary of keys from the OAuth process.
    //! @param [String] requestUrl The URL to load in the web view to begin authentication.
    //! @param [Dictionary] requestParams A dictionary of non-URL encoded parameters for the initial url.
    //! @param [String] resultUrl The URL of the final page of authentication that contains the resultKeys.
    //! @param [Number] resultType What format the result will be in. Should be a OAUTH_RESULT_TYPE_XXX value.
    //! @param [Dictionary] resultKeys A dictionary of the keys Garmin Connect Mobile will need to pull out of the OAuth response and given to the
    //!                     registered callback in registerForOAuthMessages().
    //! @since 1.3.0
    function makeOAuthRequest(requestUrl, requestParams, resultUrl, resultType, resultKeys);

    //! Register a callback for receiving OAuth messages. The callback will be called once for
    //! each received OAuth message. If there are messages waiting for the app when this
    //! function is called, the callback will immediately be called once for each
    //! waiting message.
    //! @param method [Method] The callback with the signature callback(data). data will be of
    //!                        type OAuthMessage
    //! @since 1.3.0
    function registerForOAuthMessages(method);

The makeOAuthRequest call is intended for implementing credential entry step of the OAUTH 1& 2 standard. When called, the user will receive a phone notification that your app wants to log into a web service. Clicking on this notification will take the user to a web view within Garmin Connect Mobile, where they can enter their log in information.

Credential Entry

During this time, the Connect IQ app should display a page directing the user to open Garmin Connect Mobile.  Once the user has completed credential entry, Connect Mobile will send back the tokens specified in the resultKeys option, and Connect Mobile will direct them back to the wearable.

Completed Credential Entry

Your app should call registerForOAuthMessages to receive the result of the login process. Logging in can take a long time, and a widget may time out before the user completes the login step. If your app closes before the login process completes, the result will be cached on the device until the next time your app calls registerForOAuthMessages, at which point the result will be passed to your callback immediately. Once you have the access token, you can use it as an argument to makeWebRequest.

The Wearable Web

With the new OAUTH functionality, your Connect IQ app now has a standard way to access thousands of authenticated web APIs. You can make these services available on user’s wrists.

Categories: Connect IQ SDK