Skip to content

Latest commit

 

History

History
134 lines (98 loc) · 7.21 KB

remoteBootstrap.md

File metadata and controls

134 lines (98 loc) · 7.21 KB
Raw

RemoteBootstrap

The RemoteBootstrap object provides the necessary functions to be able to configure and connect to the Hue Remote API.

Create a RemoteBootstrap

To help with connecting and configuring access to the Hue Remote API a RemoteBootstrap object needs to be created that maps to your Hue Remote API Application that you created in the development portal.

When you create a Hue Remote API Application under your developer account, it will be assigned a ClientId and ClientSecret. These can be obtained by opening the application that you created in the development portal following the details in the Remote Setup docs.

The api.createRemote() function requires two parameters:

  • clientId: The ClientId value from the Hue Remote API application that you create in the Hue Development Portal
  • clientSecret: The ClientSecret value from the Hue Remote API application that you created in the Hue Development Portal
const v3 = require('node-hue-api').v3;

const remoteBootstrap = v3.api.createRemote(clientId, clientSecret);

getAuthCodeUrl

The getAuthCodeUrl(deviceId, appId, state) function will generate the URL that you need to initiate the OAuth flow to get the OAuth tokens to access the Hue Remote API.

  • deviceId: String which is a unique identifier for the application or device using the API
  • appId: String which is the AppId of the Hue Remote API Application in the developer portal, you can get this from the details of the application you create
  • state: A String value that will be present in the response from the authentication challenge. The Hue Authorization Server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response. One good choice for a state token is a string of 30 or so characters constructed using a high-quality random-number generator.
const v3 = require('node-hue-api').v3;

const remoteBootstrap = v3.api.createRemote(clientId, clientSecret);
console.log(remoteBootstrap.getAuthCodeUrl());

The call will return a String which is the URL that your end user needs to follow in the browser to perform the redirection flow that will allow them to grant your application access to their bridge over the internet.

Upon a successful flow the Callback URL that you registered with your Hue Remote API Application in the developer portal. This Callback URL target will get the state value you passed in to the function and an authorization code.

You should validate the state value before continuing, so that you can confirm that the response is from the Hue Authorization servers.

Note: The code that is returned in the Callback URL call is only valid for a finite time, there is nothing detailed as to the extent of the time it is valid from the Hue documentation, but it definitely longer than 25 seconds at the time of writing.

connectWithCode

The connectWithCode(code, useername, timeout, deviceType, remoteBirdgeId) function will perform the second step in the OAuth authentication process following a user granting your application access to their Hue Bridge.

  • code: The authentication code that you get from the Callback URL for your Hue Remote Api Application.
  • username: An optional username that has been previously created/whitelisted in the remote API.
  • timeout: An optional timeout in milliseconds for API requests.
  • deviceType: An optional deviceType identifier for the user that will be created IF no username value is passed in.
  • remoteBridgeId: An optional id value for the remote bridge being connected to, IF no value is passed will default to an id of 0 which is correct for the majority of users, as you would need to have multiple hue bridges assigned to an account before you need to specify this value.

This function call will exchange the provided authorization code for new OAuth Access and Refresh tokens. These will be stored within the library as par of the call and can be retrieved later using the remote.getRemoteAccessCredentials() call.

Note: You need to store the OAuth tokens yourself in whatever system/location you deem necessary so that you can use them again in the future, otherwise you will have to get a new authorization code using the Callback URL. These are highly sensitive pieces of information, with them someone can fully control your bridge outside of your network!

If you do not pass in a username for the connection, one will be created for you automatically due to the majority of the remote API being useless without a user. If you leave it to the library to create the user for you, you can get the username value from the library via the library function remote.getRemoteAccessCredentials()

const v3 = require('node-hue-api').v3;

const remoteBootstrap = v3.api.createRemote(clientId, clientSecret);
remoteBootstrap.connectWithCode(code)
  .then(api => {
    // Do something with the api like getting lights etc... 
  })

The call will return a Promise that will resolve to v3 API object that you can use to access the bridge.

connectWithTokens

The connectWithTokens(accessToken, refreshToken, username, timeout, deviceType) function will perform the authentication to the Remote Hue API using previously obtained OAuth tokens.

You do not need to perform the user Callback URL process when providing existing tokens, provided that they are still valid (that is within the expiry time of their creation). Note using the refresh token you can obtain new tokens and the refresh token is valid longer than the access token, so you could wait until it expires before renewing, but there is also a time limit on the refresh token.

  • accessToken: The OAuth access token that you previously obtained (and is still valid)
  • refreshToken: The Oauth refresh token that you previously obtained (and is still valid)
  • username: An optional username that has been previously created/whitelisted in the remote API.
  • timeout: An optional timeout in milliseconds for API requests.
  • deviceType: An optional deviceType identifier for the user that will be created IF no username value is passed in.
const v3 = require('node-hue-api').v3;

const remoteBootstrap = v3.api.createRemote(clientId, clientSecret);
remoteBootstrap.connectWithCode(code)
  .then(api => {
    // Do something with the api like getting lights etc... 
  })

The call will return a Promise that will resolve to v3 API object that you can use to access the bridge.

Note: If you use this function to connect to the bridge, then the expiry times for the tokens will not be available within the library. If you do refresh the tokens using api.remote.refreshTokens() then the expiry values will be know to the library, but the tokens will be rotated adn the old ones made invalid.