Industrial Edge App User's Authorization¶

NOTICE

User authorization for Industrial Edge Apps is available for Industrial Edge Runtime 1.23.0 or bigger.

Overview¶

Industrial Edge application developers can leverage the available JWT user token, provided by the edge device, to make authorization decisions within their application. Based on the user roles, they can evaluate the permissions and grant access to different functions and data.

User roles¶

The Industrial Edge Platform offers predefined roles, which are also available to Industrial Edge Apps. These roles enable Industrial Edge Apps to define distinct access levels. Detailed information about the predefined roles can be found in the Industrial Edge Device operation manual

Retrieving the User Token¶

As part of the user's authentication process, an additional user token is generated and stored as a cookie in the user's browser, under the key access_token. This token is a crucial component in ensuring authorization capabilities to the application. By storing the token in a cookie, the application can efficiently retrieve it during subsequent interactions, ensuring that the token is readily available for authorization checks without requiring repeated backend queries.

Validating the User Token¶

The user token contains essential information needed for the application to make authorization decisions, including details about the user's identity and the roles assigned to them. To ensure the integrity of the token, the application should always validate the token against the issuer's /introspect endpoint. This endpoint allows the application to check if the token is active and has not been revoked.

Token Structure¶

The user token is a JWT (JSON Web Token) in the standard format, containing the following key information:

{
  "aud": [""],                                        
  "client_id": "authsdk",
  "exp": 1718868813,                                  
  "iat": 1718865213, 
  "iss": "urn:industrial.edge.device",                
  "jti": "50262e2f-aae7-4ec3-bcdf-23a0a7177671",      
  "nbf": 1718865213,                                  
  "roles": [                                          // roles
    "admin",
    "viewer"
  ],
  "scp": ["openid"],                                  
  "sub": "customer.admin@siemens.com"                 // subject, username
}

Validating the user token information¶

After reading the user token, the application should always validate the token against the issuer's /introspect endpoint in order to ensure that the information stored in the token was not altered. The introspection endpoint allows to check if a token is active or not. An active token is neither expired nor revoked.

The /introspect check is accessible via POST call to the endpoint: https://<device-ip>/device/edge/auth/oauth2/introspect/ or over the internal network from the app via the proxy-redirect https://edge-iot-core.proxy-redirect/device/edge/auth/oauth2/introspect

Below is an example of how to validate a specific user token, providing the encoded token as a content-type of application/x-www-form-urlencoded.

curl -k --location --request POST 'https://<device-ip>/device/edge/auth/oauth2/introspect/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=...user_token_here...'

Example of an active token response from the /introspect endpoint.

{
  "active": true,
  "scope": "openid",
  "client_id": "3bec1184-887b-494c-8166-f7e87d2b6fac",
  "sub": "customer.admin@siemens.com",
  "exp": 1719497326,
  "iat": 1719493726,
  "nbf": 1719493726,
  "aud": [],
  "iss": "urn:industrial.edge.device",
  "token_type": "Bearer",
  "token_use": "access_token",
  "ext": {
    "roles": [
      "Admin"
    ]
  }
}

Example of an inactive token response from the /introspect endpoint.

{
  "active": false
}

Invalidating the user token¶

During the logout action of the user, the generated user token cookie is removed from the browser and a new user token will be generated upon the next user authentication action.

How to use the token in an application¶

To use the token in an application, follow these steps:

create your application
retrieve the access_token cookie and validate it at the /introspect endpoint
package the application and consider:
configure a reverse proxy
the "Secure Redirection" option must be checked

When the application is using the "Secure Redirection" option you can only access the application if you are logged in. This makes sure that the user always has a valid user token.

For more information on how to build your own application please check the overview documentation.

You can find more information about the reverse proxy and Secure Redirection here.