Sometimes you need to access to a third-party service whose authentication is managed using the same IdM service used by the WireCloud instance. In those cases, you can make use of the support provided by WireCloud for injecting the OAuth2 token obtained from the IdM server into the requests made from your widgets/operators.

WireCloud provides this token injection support through the WireCloud's proxy, which is the component in charge of injecting the token. If you want to use the tokens obtained from the IdM, you must use the WireCloud's proxy (e.g. by using the MashupPlatform.http.makeRequest method). WireCloud doesn't provide support for reading OAuth2 tokens from widgets/operators.

Note: This document uses the headers names available on WireCloud 0.9.1+ for simplicity, but previous versions of WireCloud use other names. See the latest slide for more info.

How to use the token injection support

All the configuration about how to inject the OAuth2 token into your requests is provided using HTTP headers that will be consumed by the WireCloud's proxy. The main header is: FIWARE-OAuth-Token. This header should be added to any requests (providing true as value) in which we want to inject an OAuth2 token.

Take into account that anonymous users doesn't have a valid OAuth2 token. Also, if you are running a custom instance of WireCloud it can be configured to support several auth backends. In that case, some user won't be associated with an IdM account. You can check if the currently logged user has an associated IdM token by running the following code:

MashupPlatform.context.get('fiware_token_available');

into HTTP headers

Usually you will want to inject the OAuth2 token into an HTTP header, this can be accomplished by using the FIWARE-OAuth-Header-Name header. Tipically, you will want to add the token into the X-Auth-Token header (as used by Open Stack) or into the Authorization header (as dictated by the OAuth2 RFC). If you inject the OAuth2 token into the Authorization header, WireCloud will add the token type prefix accordingly (e.g. Bearer).

Example:

MashupPlatform.http.makeRequest(url, {
    requestHeaders: {
        "FIWARE-OAuth-Token": "true",
        "FIWARE-OAuth-Header-Name": "X-Auth-Token"
    },
    ...
});

as GET parameters

Another common place for injecting the OAuth2 token is into a GET parameter on the URL. This kind of injection is configured using the FIWARE-OAuth-GET-Parameter header.

Example:

MashupPlatform.http.makeRequest(url, {
    requestHeaders: {
        "FIWARE-OAuth-Token": "true",
        "FIWARE-OAuth-GET-Parameter": "access_token"
    },
    ...
});

This will add an access_token GET parameter into the URL containing the OAuth2 token of the currently logged user.

into the body of the request

Finally, the proxy can inject OAuth2 tokens into the body of the request. To do so, you have to provide the pattern to be searched and replaced with the OAuth2 token using the FIWARE-OAuth-Body-Pattern header.

Example:

MashupPlatform.http.makeRequest(url, {
    method: 'POST',
    postBody: JSON.stringify({token: "%fiware_token%"}),
    requestHeaders: {
        "FIWARE-OAuth-Token": "true",
        "FIWARE-OAuth-Body-Pattern": "%fiware_token%"
    },
    ...
});

This will search for any %fiware_token% ocurrence in the body of the request and replace it with the OAuth2 token of the user.

WireCloud 0.7.2+ provides experimental support for using the OAuth2 token of the owner of the dashboard instead of using the OAuth2 token of the current logged user. To do so, add the FIWARE-OAuth-Source header into your request and use the workspaceowner value. This header can be used in combination with any of the previously presented headers: FIWARE-OAuth-GET-Parameter, FIWARE-OAuth-Header-Name or FIWARE-OAuth-Body-Pattern.

Example:

MashupPlatform.http.makeRequest(url, {
    requestHeaders: {
        "FIWARE-OAuth-Token": "true",
        "FIWARE-OAuth-Header-Name": "X-Auth-Token",
        "FIWARE-OAuth-Source": "workspaceowner"
    },
    ...
});

Version 0.9.0 and below of WireCloud uses another set of the header names. They were prefixed with X- and had a dash inside the FIWARE word. For example, FIWARE-OAuth-Token was named X-FI-WARE-OAuth-Token. In addition, the header for indicating the body pattern was further restructured.

Old names can still be used but will be removed in WireCloud 1.1