Authentication and Authorization¶

This section describes the most important aspects of authentication and authorization within Insights Hub. This will help you quickly get started with the Insights Hub APIs. After referring to this introduction, you will be able to do the following:

• Call Insights Hub APIs from Cloud Foundry applications.
• Call Insights Hub APIs from frontend applications (e.g., an AJAX call from JavaScript).
• Secure your application with an application specific scope.

Introduction¶

All Insights Hub endpoints are secured and can be reached only after successful authentication. You will then be provided with a token that can be obtained in different ways, as described in the following sections. The token will contain information about what you are allowed to do, e.g., what APIs you are allowed to use.

Get a Token to call Insights Hub APIs from your Application¶

Your application requires a valid token for calling Insights Hub APIs. If a logged-in user accesses your application, either via the Launchpad or by directly calling the application URL, a token (a bearer token) is passed as a header in the request to your application.

There are two ways of calling Insights Hub APIs from applications:

• Calling APIs from the backend (e.g., Cloud Foundry) by using gateway.{region}.{mindsphere-domain}/api/...
• Calling APIs from the frontend is relatively easy {web_app_host}/api/...

Calling APIs from the Backend¶

Calls from the backend to Insights Hub APIs must send an authorization header with every request. Extract the header information from the request to your backend and reuse the authorization header in your requests to Insights Hub APIs.

Java¶

The following Java Code Snippet prints out all available headers and returns the token.

private String extractToken(HttpServletRequest request) {
  Enumeration<String> headerNames = request.getHeaderNames();
    while (headerNames.hasMoreElements()) {
      String header = headerNames.nextElement();
      LOGGER.info("header " + header +  " " + request.getHeader(header));
    }
    return request.getHeader("authorization");
}

Add this token as an authorization header when sending requests to the Insights Hub APIs listed in the Important URLs section.

Node.js¶

The following Node.js Snippet uses expressjs and superagent to access an API; line 7 contains placeholders for the region and domain.

var request = require("superagent");
...

app.get('my-route', function (req, res) {
  authHeader = req.get("authorization");
  request
  .get('https://gateway.{region}.{mindsphere-domain}/api/identitymanagement/v3/Users?attributes=meta,name,userName,active')
  .set('authorization', authHeader)
  .set('Accept', 'application/json')
  .then(function(data) {
      res.json({
        resources: data.body.resources
      });
  }).catch(err => {
      console.error(err.message, err.status);
      res.status(err.status).json({ message: 'Failed to fetch users.'});
  });
});

...

Calling APIs from the Frontend¶

When calling APIs from the frontend, the authorization header is not required. Reuse the sessionid that is set as a cookie instead and send the following header, which is provided as a cookie (e.g., x-xsrf-token:e4edcb6c-bd1c-46c1-863c-421235c522a3) by the Industrial IoT Gateway:

x-xsrf-token:{XSRF-TOKEN}

The following example uses the Fetch API:

let myXRSFToken = ...

fetch('/api/identitymanagement/v3/Users', {
  credentials: 'include',
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "x-xsrf-token": myXRSFToken
  }
})
...

Secure Access to your Application¶

As a developer, you must ensure that no untrusted or unauthorized users can access your application. We provide a security concept using roles, scopes and tokens for every registered application. For more information, refer to the Roles & Scopes section.

Example¶

In this example, an application (every endpoint) is protected using expressjs and a custom middleware that intercepts every request and verifies that the request token contains an application-specific scope.

var jwt = require('jsonwebtoken');
var path = require('path');
var includes = require('lodash/includes')

const express = require('express')
const app = express()

// Middleware for checking the scopes in the user token
app.use('/', function (req, res, next) {
  const authorizationHeader = authHeader = req.get("authorization");
  var scopes = [];

  if (authorizationHeader != null) {
    token = jwt.decode(authorizationHeader.replace("bearer ", ""), { complete: true, json: true })
    scopes = token.payload.scope;
  }

  console.log("scopes: ", scopes); // output all scopes

  if (includes(scopes, `${config.mdsp.appname}.${config.mdsp.scope}`)) {
    console.log("request with valid application token")
    next();
  } else {
    console.log("unauthorized request");
    res.status(403).send('no access!');
  }
});
...

Token Validation¶

Access tokens issued by Insights Hub are JSON Web Tokens (JWTs) as defined in RFC 7519. It is recommended to validate all tokens consumed by your application as described in RFC 7519 - Section 7.2. This validation can be performed offline, i.e., without sending the token to another service.

Validation Recommendations¶

The following sections provide additional hints for the token validation.

Payload Validation¶

Validate the access token using the following payload claims:

Signature Validation¶

1. Verify that the access token is signed with a trusted and expected algorithm by checking the value of the alg claim. Insights Hub does not issue JWTs with alg = none. Currently, the Insights Hub signs all tokens using RS256.
2. Verify that the kid claim in the token header refers to a public key that is valid in the context of the token issuer.
3. Verify the token signature using the referenced algorithm and the public key.

The key pairs for the creation and verification of token signatures are regularly updated. Components using those keys should regularly check for updates.

Except where otherwise noted, content on this site is licensed under the Development License Agreement.