OAuth 2.0

Posted on
Thu Nov 22, 2018 12:42 pm
lochnesz offline
Posts: 366
Joined: Oct 01, 2014
Location: Stockholm, Sweden

OAuth 2.0

Hi,

I have no experience at all from OAuth, but would like to use a JSON based API which requires OAuth 2.0. Is this doable with python in Indigo?

I have a Callback URL(don't know what this does), Identifier and Secret with the API supplier.

Thanks!
Peter

Posted on
Thu Nov 22, 2018 12:47 pm
FlyingDiver offline
User avatar
Posts: 7189
Joined: Jun 07, 2014
Location: Southwest Florida, USA

Re: OAuth 2.0

Very tricky. I've been doing some experimenting with various services that use OAuth authentication, and I haven't found one you could use with just the client-side API.

Ecobee uses OAuth, but has an alternative PIN based authentication that works in the plugin. Slack also uses OAuth, and the only way to make it work (so far) is to register as a developer on their site and get an OAuth token directly from the developer website.

What service is it you're trying to use? I can take a look at their API and tell you if you'll be able to make it work.

joe (aka FlyingDiver)
my plugins: http://forums.indigodomo.com/viewforum.php?f=177

Posted on
Thu Nov 22, 2018 1:19 pm
lochnesz offline
Posts: 366
Joined: Oct 01, 2014
Location: Stockholm, Sweden

Re: OAuth 2.0

I would like to use the API from https://api.nibeuplink.com/ to manage my heat pump.

The NIBE Uplink API is a RESTful api, relying on established conventions from the HTTP specification. As an example, the API relies on the client to use HTTP methods such as GET, POST, PUT, DELETE to describe the action to perform on a resource and it indicates the success or failure of that action by returning a HTTP status code.

All access is over HTTPS, and is provided over the api.nibeuplink.com domain.
Data Format

All data is sent and received as JSON. The client needs to specify the Content-Type and Accept headers as either application/json or text/json.

Blank fields are included as null instead of being omitted. All timestamps are returned with the ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ) in UTC.
Parameters

API functions have both required and optional parameters. For GET requests, parameters not specified in the request URL, no matter if they are required or optional, should be provided as query paramaters. For POST, PUT and DELETE requests, the same parameters should be provided as JSON in the request body.
Parameter example
The following API functions has one parameter specified in the request URL (systemId and type), and a couple of required and optional parameters which are not (type, active, page and itemsPerPage)

GET api/v1/systems/{systemId}/notifications/

And can therefore be called either with only the mandatory parameters or with any of the optional parameters

GET api/v1/systems/435/notifications/?type=INFO_MESSAGE
GET api/v1/systems/435/notifications/?type=INFO_MESSAGE&active=false&itemsPerPage=5

Error Messages

The NIBE Uplink API uses HTTP response codes, as defined in the HTTP specification, to indicate the success or failure of a request. In general, response codes in the 2xx range indicate success, 4xx range indicate an error that resulted from the provided information (e.g. lack of access to resource, missing required parameter) and response codes in the 5xx range indicate an error with the NIBE Uplink servers.

All non-successful response messages contains an error message object to help troubleshoot the issue on the client side. For OAuth authorization and token requests this response message follows the convention specified in the OAuth 2 specification. Other requests responds with a JSON object with the following parameters.
Name Description Type
httpStatusCode

The HTTP status code returned
integer
errorCode

An error status code
ErrorCodes
timestamp

A timestamp indicating when the error occured
string
details

List of descriptive text messages in English detailing the error
list of strings
data

Additional data to help with handling of the error
dictionary of string [key] and string [value]
HTTP Redirects

Where appropriate, the API may use HTTP redirects. Clients should assume that any request may result in a redirection within the api.nibeuplink.com domain. Receiving a redirection does not imply that an error has occured.
Status code Description
301

A permanent redirection, signaling that the resource / function has been renamed.
302, 307

A temporary redirection, signaling that for the current request the client better call another function instead.

Pagination

Functions that return multiple items are paginated. In the case of pagination the function reference documentation specifies which default values are used and how to access further pages.
Rate Limiting and Client Abuse

The NIBE Uplink API is rate limited. All requests reaching the NIBE Uplink API is counted and when the limit has been reached the following requests will get an error message with the HTTP status code 429 in return. The current limit for public API clients is one request every 4th second with occasional bursts allowed. These limits can be be adjusted at any time without notice if deemed necessary.

If an application or client is found abusing the API in any way, NIBE Energy Systems has the right to block it until the client owner has solved the issues highlighted by NIBE.


Authentication

For a client to be allowed to communicate with the NIBE Uplink API it needs to be registered with NIBE Uplink. When registering a client a client key and a client secret are generated and supplied to the client owner. It is up to the client owner to make sure these are not leaked to a third party. If the client owner suspects the client key and secret could have been leaked, it is the client owner's responsibility to notify the NIBE Uplink team about the potential leak in order to block any malicious activity done in the name of their client.
User Authentication

Currently, all requests to the NIBE Uplink API requires a valid user authentication. The user authentication makes sure that the client can only access the resources for that particular user.

Users are authenticated via the OAuth 2 protocol. NIBE Uplink currently supports the Authorization Code Grant flow and the Implicit Grant flow. The Authorization Code Grant flow targets clients which the OAuth 2 specification deems confidential, such as web applications and mobile apps while the Implicit Grant flow is a shorter flow which targets public clients that can't keep the confidentiality of the OAuth credentials, such as browser based JavaScript applications.

Under no circumstances is the client allowed to process or handle a user's secret login credentials.

The following URL:s are used for the OAuth 2 requests

Authorize endpoint https://api.nibeuplink.com/oauth/authorize
Token endpoint https://api.nibeuplink.com/oauth/token

Scope

When authenticating with the NIBE Uplink API you need to specify how your application wants to access the API through the Scope parameter. Depending on which scopes you have requested and have been granted by the user you will have access to different functionality. Each function in the function list clearly specifies which scope is required in order to access that particular function.
Scope Description
READSYSTEM Gives access to reading system status and stored parameters
WRITESYSTEM Gives access to change settings on systems


Authentication Examples
Example: Authorization Code Grant
The Authorization Code Grant takes place in 4 steps as outlined below. Before starting to authenticate you need to have registered your application and received a client id and secret.
1. Redirect the user's browser to the OAuth2 authorization page.
Redirect the user's browser to the address outlined below. Make sure to exchange the [CLIENT_ID], [SCOPES] and [REDIRECT_URI] with the correct values for your application.

https://api.nibeuplink.com/oauth/author ... client_id=[CLIENT_ID]&scope=[SCOPES]&redirect_uri=[REDIRECT_URI]&state=[STATE]

2. The user authorizes your application.
The user will now be prompted with a login form (if not already logged in) and the question whether they would like to give your application access to their data.
3. The user is redirected to your application with authorization data.
When the user has authorized your application he/she will be redirected back to the redirect_uri you specified to the authorize endpoint with the data you need to gain access to the account. Always check that the state parameter returned is equal to the one supplied to the authorization endpoint.

[REDIRECT_URI]?code=[AUTHORIZATION_CODE]&state=[STATE]

4. Your application uses this authorization data to gain access to the account.
Using the data you received in the last step you can call the token endpoint and get an access token and a refresh token that can be used in the following communication.

POST /oauth/token HTTP/1.1
Host: api.nibeuplink.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=authorization_code&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&code=[AUTHORIZATION_CODE]&redirect_uri=[REDIRECT_URI]&scope=[SCOPES]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"access_token":[ACCESS_TOKEN],
"expires_in":300,
"refresh_token":[REFRESH_TOKEN],
"scope":[SCOPES],
"token_type":"bearer"
}

5. Authenticate the subsequent requests.
Once the access token has been retrieved it can be used immediately and until the expires_in seconds has passed to access resources in the NIBE Uplink API. To access token needs to be provided as a bearer token to the API endpoints.

GET /api/v1/systems HTTP/1.1
Host: api.nibeuplink.com
Authorization: Bearer [ACCESS_TOKEN]

Example: Refresh Token
Once the access token has been retrieved it can be used immediately and until the expires_in seconds has passed. After that the access token has to be renewed and this can be done using the refresh_token (only available in the Authorization Code Grant flow). This is done by calling the token endpoint with the refresh token.

POST /oauth/token HTTP/1.1
Host: api.nibeuplink.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=refresh_token&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&refresh_token=[REFRESH_TOKEN]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"access_token":[ACCESS_TOKEN],
"expires_in":300,
"refresh_token":[REFRESH_TOKEN],
}


Posted on
Thu Nov 22, 2018 1:39 pm
FlyingDiver offline
User avatar
Posts: 7189
Joined: Jun 07, 2014
Location: Southwest Florida, USA

Re: OAuth 2.0

Is there any documentation on the "Implicit Grant flow" authorization method? The "Authorization Code Grant" method would be very difficult to do from a plugin.

Unfortunately, I can't create an account without a European address. I guess I could try to make one up.

joe (aka FlyingDiver)
my plugins: http://forums.indigodomo.com/viewforum.php?f=177

Posted on
Thu Nov 22, 2018 1:53 pm
lochnesz offline
Posts: 366
Joined: Oct 01, 2014
Location: Stockholm, Sweden

Re: OAuth 2.0

I looked through the documentation but I can't find anything more on Implicit Grant flow. I can send an e-mail to NIBE to get more information about it. What exactly should I ask?

(If you'd like an account I can send you a valid European address in a PM)

Posted on
Thu Nov 22, 2018 1:56 pm
lochnesz offline
Posts: 366
Joined: Oct 01, 2014
Location: Stockholm, Sweden

Re: OAuth 2.0


Posted on
Thu Nov 22, 2018 2:26 pm
FlyingDiver offline
User avatar
Posts: 7189
Joined: Jun 07, 2014
Location: Southwest Florida, USA

Re: OAuth 2.0

So, your best bet is to do everything in that blog post, except you'll need to translate that final script to Python to run it as an external script from Indigo. And modify it to update Indigo variables instead of just printing out the data.

Or convert it to a plugin.

You can see from the blog post the issues with getting the initial authentication token. Dealing with refreshing the tokens isn't too bad, my Ecobee plugin does that.

I was able to create an account so I can read all the docs. You're right, there's no example of the other authentication method.

joe (aka FlyingDiver)
my plugins: http://forums.indigodomo.com/viewforum.php?f=177

Posted on
Thu Nov 22, 2018 2:29 pm
lochnesz offline
Posts: 366
Joined: Oct 01, 2014
Location: Stockholm, Sweden

Re: OAuth 2.0

I will give it a go, hoping for the best 8)

Thanks!

Page 1 of 1

Who is online

Users browsing this forum: No registered users and 2 guests