Skip to content

Enable Identity Federation on Devices

What is the Identity Federation or Single Sign-On Feature for the Devices and how does it work

The Identity Federation to IEM feature enables single sign-on (SSO) between Industrial Edge Management and devices. This allows users to securely authenticate with their Industrial Edge Management credentials on all devices where the feature is enabled.

For this purpose, an OIDC client is created on the Industrial Edge Management side (Keycloak) to enable session sharing between the Industrial Edge Management and the device. The login flow can be described as followed:

The function also configures an initial logon flow for existing and new users. For Identity Federation to the IAM, it works like this:

  • if the user already exists on the device, it will be linked to the external identity based on the email.
  • if the user does not exist on the device, it will be created based on the information of the external identity.

Further information about the mapping can be found here

NOTICE

By default a time offset of 5 seconds between the issuer, Industrial Edge Management, and the Device is accepted. To change it manually, follow the instructions in the chapter API description.

Who has access?

Users must meet the following requirements:

  • The user exists on the IAM.
  • The user's email has been verified.
  • Valid credentials are provided.
  • A role for that device has been assigned to the User.

Enable Identity Federation

To enable the feature on a device, you must either

  • be the Owner of the Device, or
  • have the Role "Device Owner" assigned.

If you have either of these, you can log in to your IEM and navigate to your Devices page:

NOTICE

The feature is only available in the new UI Experience.

In this view, you can navigate to your device and click on the ... icon and select Enable Identity Federation. A new window displays more information about the feature and asks you to confirm the action.

After clicking enable a job will be added for the device. You should see a pending job in your Job Tab. After the device has picked it up, it should jump to successful.

NOTICE

If encountering issues, have a look in the known issue section

If successful, the job has created a Client in your IAM and has also taken care of configuring the feature on the Device. To verify this, you can take a look at your IAM, where you should now see a Client with the name of your Device, the Client name will follow the following notation: ie-device-<device-name>. This newly created client will have the following roles: Admin, User, Viewer, Operator, and AppAdmin. The Viewer, Operator, and AppAdmin roles are composite roles that include the User role as a child role. For more details on the available roles, please refer to the Industrial Edge Device operation manual

NOTICE

Devices with a runtime version lower than 1.23.0 do not support the Viewer, Operator, and AppAdmin roles. In these cases, the roles are interpreted as the User role.

NOTICE

  • Making changes to this client can result in a non-functional configuration for your Identity Federation. For more information click here.
  • Removing or resetting a device with Identity Federation enabled does not automatically clean up the identity provider client on your IAM. Please see here for more details.

Assign User Role to Access Device

To allow a user to access the device using their IEM credentials, they must be assigned an appropriate role from the newly created IAM client mentioned in the previous section. For more information, see Role assignments.

You will find the client roles for your Device (ie-device-<device-name>), when you filter by clients. To allow access to the Device, select and assign the specified Role (User/Admin).

The email must be verified. See SMTP Verification for an explanation of why this is there and how to configure it. To manually verify the user's email, simply go to the user's details and set "Email verified" to Yes

Login on the device

After completing the above steps, you can now navigate to your Device Login Page. You will find an additional login option Or sign in with.

Clicking "IEM Login" if you are not already logged into the IEM will take you to the IEM Login page. Enter your IEM Credentials.

Upon successful login, you will be returned to the Device page. If you already have a valid session on the IEM, you will be logged in directly to the device.

Enable and Disable Local Login

For users created during the initial logon flow with the IAM, Local Login is disabled by default. If you want to give these users local logon access, you must reset the existing user's password.

Make sure you have Admin Rights on the Device. Go to the Settings Page and click on Members.

The ... symbol will show you the option to generate a reset token.

This token can be used on the Login Page.

Click reset Password and enter the user information and the Reset Token.

NOTICE

For Admin Users there are some restrictions. Click here for more information.

Disable Identity Federation

To disable the Identity Federation between the Device and the Industrial Edge Management, follow the steps from Enable Identity Federation to get to the new User Experience UI. In the dropdown menu you will see the option Disable Identity Federation. Click on it and confirm the disable action.

NOTICE

Disabling Identity Federation will also remove all access settings for the selected device on the IEM.

NOTICE

Configuration on the device and on Keycloak must be cleaned up. If you get a warning on disable, refer to known issues

Enable Identity Federation and use via Remote Access connection

One of the advantages of Identity Federation, is enabling the management of device users on the IT Layer, allowing a better integration with existing IT Systems. Additionally the remote access leverages the already existing connection between the Industrial Edge Management and the devices, giving the users the possibility to reach devices remotely. The combination of these features provides more flexibility for reaching and authenticating on the devices.

The use of Identity Federation for login over Remote Access is available from the Industrial Edge Management App version 1.17.n or higher, in combination with a device containing the IE runtime version 1.18.0-n or higher.

If you want to leverage the Remote Access connection to your device and access the device remotely while authenticating using your IEM credentials, follow these steps:

  1. On the Edge Devices overview click on the three dots and select Enable Remote Access , confirm any following pop-ups that may appear.

  2. Activate Identity Federation for the device as described in the previous section Enable Identity Federation.

  3. Click on the device tile to go to your device details.

  4. Once in the Device details menu, on the top left corner, you should see a link reading Connect, click to reach your device.

  5. You will be redirected to your device via the remote connection, now you can login via Identity Provider as described in Login on the device.

Limitations / Problems and Solutions

Known Issues

NOTICE

With remote access enabled, if a K8s IEM becomes inaccessible, it takes up to 7 minutes to connect via remote access once the IEM is connected to the IED. With remote access enabled, if a non-K8s IEM becomes inaccessible, it takes up to 15 minutes to connect via remote access once the IEM is connected to the IED.