<- Up: Documentation Home

OAuth2 Sample

This section provides a hands-on example on how to perform an OAuth2 authentication with the free@home cloud API. If you already have a functional OAuth2 implementation, you can skip this section entirely.

OAuth2 is a standard/protocol for secure authentication. A full description of OAuth2 is out of the scope of this section (there are plenty of good tutorials and documentations available on the internet). For myBUILDINGS-specific detailed OAuth2 documentation, please refer to the OAuth2 Authentication Flow section. The myBUILDINGS portal supports several use-cases, but in this example only a single common use-case is presented.

In this example we assume you want to monitor or control a free@home system access point (SysAP) using the free@home cloud API from a different computer (for example your notebook, a server you control or simply a raspberry pi). For this you require an OAuth2 token that can be used to execute the free@home cloud API calls, as presented in the samples. Obtaining this token is the subject of this sample.

Prerequisites

Before you begin this sample, please make sure that your developer account for the free@home cloud API is fully functional and you have a SysAP available in the cloud that is fully set up. To verify this, you can use the cloud API directly on the developer portal, by using the “Try it” button with the Get Configuration (/api/rest/configuration) call (remember to fill in the “Authorization” headers - the portal will obtain a valid token for you).
If this call returns the configuration of your SysAP, then your account is ready. Otherwise please refer to the prerequisites for the free@home cloud API section.

Additionally, you require your OAuth2 credentials:

  • User ID (this is a UUID of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
    NOTE: This User ID (or also “client ID”) is NOT the username that you use to log into the developer portal or to the myBUILDINGS portal. You should have received an additional User ID of the form above.
  • User Secret
  • Redirect URL (this URL has the form https://api.eu.mybuildings.abb.com/external/oauth2helper/code/set/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, with the last part being your User ID).
    Note that this sample requires that the redirect URL uses the OAuth Helper Service provided by the myBUILDINGS portal. This example does not need this URL, but it is normally provided along with User ID and User Secret.

If you did not receive these information, please contact the ABB developer portal team.

OAuth2 authentication

The general overview of our approach is:

  1. (S) Contact the portal to start the OAuth2 authentication.
    The result is an authorize_url, a code_url and a accesstoken_request_url.
  2. (E) Open a web browser at the authorize_url and login to the myBUILDINGS portal using the myBUILDINGS of the end user who owns the SysAP.
  3. (S) Poll the code_url.
    The result (once the user logged in) is a code.
  4. (S) Contact the portal with the OAuth2 credentials and the code to obtain the OAUTH2_ACCESS_TOKEN.

The steps marked with (S) are performed by your script/application (e.g. on your server) and can be automated. The step marked with (E) must be performed by the end user, as it requires knowledge of the account credentials of the end user, which the scripts in this example never learn about (this is a core concept of OAuth2 - the users never reveal their passwords).

In the following, this example uses the curl command line tool for the steps marked with (S) above. For a productive version a different approach would be more convenient, because it is required to parse JSON strings, which is inconvenient using the command line only. A simple solution is a python based script, for example using the requests library to make HTTPS requests.

Contact the portal to start the OAuth2 authentication

To start the OAuth2 authentication, send a POST request to https://api.eu.mybuildings.abb.com/external/oauth2helper/config/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where the last part is your OAuth2 User ID (NOT the myBUILDINGS portal account of the end user):

curl -X POST https://api.eu.mybuildings.abb.com/external/oauth2helper/config/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The response is a JSON string containing a JSON object:

{
  "authorize_url":"https:\/\/eu.mybuildings.abb.com\/sso\/authorize?response_type=code\u0026client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\u0026state=STATE_STRING",
  "code_url":"https:\/\/api.eu.mybuildings.abb.com\/external\/oauth2helper\/code\/get\/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?state=STATE_STRING",
  "accesstoken_request_url":"https:\/\/eu.mybuildings.abb.com\/sso\/token"}

The result has been shortened and formatted for readability. Make sure to parse the JSON properly, to remove the escaping (replace \/ by / and \u0026 by &), otherwise pasting the URLs in the next steps will not work.

  • The authorize_url provides the User ID you used in the request and a (very long) STATE_STRING generated by the portal.
  • The code_url likewise uses the User ID you used in the request and the STATE_STRING.
  • The accesstoken_request_url should be https://eu.mybuildings.abb.com/sso/token.

Open the authorize_url

Once the authorize_url has been obtained from the portal, the end user must navigate to this URL. This can be done by simply pasting this URL into a web browser, by opening the URL in a browser component in your application or by whatever means are appropriate to you.

This URL belongs to the myBUILDINGS portal. The end user is to use this URL to log into his or her myBUILDINGS account (the same account that the SysAP uses).

Note that in the approach used by this sample, it does not matter on which device the user opens this URL, it does not have to be the same computer that performs the other steps.

Poll the code_url

Once the end user has logged into his or her account, the OAuth2 authentication can continue. Since that steps requires manual intervention, your script or application may have no way to know when this step is finished - for this, you can simply poll the URL provided as the code_url in the first step. This URL will return success (HTTP 200 response) when the user logged in successfully and otherwise will return an error (HTTP 404). On success, this URL provides a code that is required for the last step. NOTE This code is short-lived (30-60 seconds). It should be used once received.

It is recommended to poll every 5-10 seconds, to make sure the code can be used in a reasonable amount of time (i.e. to match the 30-60 second time window of the lifetime of the code).

curl https://api.eu.mybuildings.abb.com/external/oauth2helper/code/get/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?state=STATE_STRING

Response:

{"code":"0123456789abcdef0123456789abcdef01234567"}

Contact the portal with the OAuth2 credentials and the code to obtain the OAUTH2_ACCESS_TOKEN

Finally, send the code obtained in the previous step, the User ID (client_id) and the User Secret (client_secret) from your OAuth2 credentials to the portal at https://eu.mybuildings.abb.com/sso/token:

curl -X POST \
    https://eu.mybuildings.abb.com/sso/token \
    -d 'grant_type=authorization_code' \
    --data-urlencode 'scope=RemoteControl Monitoring RegisterDevice' \
    -d 'code=0123456789abcdef0123456789abcdef01234567' \
    -d 'client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
    --data-urlencode 'client_secret=OAUTH2_CLIENT_SECRET'

Response:

{
  "access_token":"OAUTH2_ACCESS_TOKEN",
  "expires_in":3600,
  "token_type":"bearer",
  "scope":"RemoteControl Monitoring RegisterDevice",
  "refresh_token":"OAUTH2_REFRESH_TOKEN"}

The token_type is always “bearer”, meaning this access_token should be used in the Authorization: Bearer OAUTH2_ACCESS_TOKEN header. The scope should match the requested scope (this gives you the listed permissions for the SysAP) and expires_in indicates how long this token is valid.

With this token you can perform the free@home cloud API calls. See the samples for sample calls.

When the token is about to expire, you can use the OAUTH2_REFRESH_TOKEN to request a new token without another manual intervention (login) from the end user. See the detailed OAuth2 documentation for an example.