Configure SAML single sign on (SSO) in IT Expert

[EcoStruxureIT]

Administrator users and partners can configure SAML 2.0 single sign on in the Administration > More > SSO option in IT Expert. Any identity provider (IdP) that supports the SAML protocol is supported. 

An EcoStruxure IT Expert subscription is required.

Once you configure SSO, all users with an email address on one of the domains you specify must use your identity provider to log in to IT Expert.

You can still use the IT Expert Administration > Users option to invite and manage users from email domains not using the domains you specify for SSO.

If your SSO certificate expires, you must reset your SSO configuration.

idea_icon_4403017628561.png

It is strongly recommended that at least one Administrator user who does not require SSO to log in is configured in IT Expert Administration > Users. If you subscribe devices to EcoStruxure Asset Advisor and configure SSO, you must also configure your organization's users on the Administration > Users tab. Otherwise, the Schneider Electric Service Bureau cannot contact the individuals responsible in case of an incident.

In this article

• Configure your identity provider
• Supported SAML attributes
• Configure SSO in IT Expert
• 1. Enter SAML details
• 2. Test SAML configuration
• 3. Verify domain ownership
• Enable Identity Provider (idP) Initiated SSO login
• Update your SAML SSO certificate or sign-in URL
• Reset SSO configuration

Configure your identity provider

Azure users also see Configure Azure AD for IT Expert SAML SSO

Before you configure SSO in IT Expert, use the Identity Provider details on the Administration > More > SSO page to configure the integration with IT Expert in your identity provider's user interface.

Refer to your identity provider's documentation for more information.

1. Log in to IT Expert and go to Administration > More > SSO.

2. Copy and paste the SAML Assertion Consumer Service (ACS) URL and the SP Entity ID in the appropriate fields. These values are specific to your account.

   Note: The SP Metadata URL will be displayed in step 2 of the IT Expert configuration. Some identity providers require it.

3. IT Expert requires that you configure your identity provider to send these three SAML attributes:

• "name": How user names are displayed
• "email": User email address
• "groups": The groups your IT Expert users are members of
  Note: Groups configuration is not applicable for partners.

If your identity provider does not support adding the SAML attributes above, see the full list of supported SAML attributes below to use as alternatives.

You can create groups in both your identity provider and IT Expert; group names must match exactly in both. You can assign access permission for each group on the IT Expert Administration > Groups tab. See IT Expert permissions

Note: IT Expert contains two groups by default, Administrators and Users.

Users you want to have Administrator rights in ITE must have a group SAML attribute with the value "Administrators."  Users who should have regular user rights in ITE must have a group SAML attribute with the value "Users." Users without a group SAML attribute will not have access to ITE. 

Consult the documentation for your identity provider to learn about adding SAML attributes.

Note: Every time a user logs in using SSO, the identity provider sends EcoStruxure IT a list of the groups the user belongs to. If any changes to group assignments are needed, you make the changes in your identity provider, not in IT Expert.

Supported SAML attributes

EcoStruxure IT supports these attributes, if, for example, your identity provider only supports InCommon Federation Attributes, or other standard attributes:

SAML attribute	Description
name	Display name of the user
displayname
urn:oid:2.16.840.1.113730.3.1.241
http://schemas.microsoft.com/identity/claims/displayname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
email	E-mail address of the user
urn:oid:0.9.2342.19200300.100.1.3
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
phone	Phone number of the user
phoneNumber
telephoneNumber
urn:oid:2.5.4.20
urn:oid:0.9.2342.19200300.100.1.20
urn:oid:0.9.2342.19200300.100.1.41
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone
group	List of groups the user is a member of
groups
urn:oid:2.16.840.1.113719.1.1.4.1.25
http://schemas.xmlsoap.org/claims/Group

Configure SSO in IT Expert

Your identity provider will provide the information needed to configure SSO in IT Expert.

Return to IT Expert Administration > More... > SSO.

1. Enter SAML details

1. Copy the SAML SSO sign-in URL from your identity provider into the SAML SSO sign-in URL field.

   In Azure, this is the User access URL under Properties.

   The URL must start with https://

2. Upload your SAML SSO certificate or paste it into the text field. The certificate must be x.509 in *.PEM or *.CER format.

   The certificate must start with:
    ‘-----BEGIN CERTIFICATE-----’
   and end with:
   ‘-----END CERTIFICATE-----’ 

   The certificate expiration date is automatically extracted from the valid certificate and cannot be edited.

3. Specify your Sign-in email domain(s). For example, if user email addresses are user@mydomain.com, enter mydomain.com in the field.

   Separate multiple domains with a comma, or use the Enter or Tab keys.

   Note: All users with an email address on one of the domains you specify must use your identity provider to log in to IT Expert.

   

The Continue button is enabled when all the field are populated and valid.

2. Test SAML configuration

Verify that your SAML connection is configured properly. 

1. Open a different browser or an incognito window.

2. Go to https://ecostruxureit.com and click Log in. Choose Customer. 

3. Enter the test email address shown in ITE. 

   The password field will disappear, and the login for your identity provider will be displayed.

4. Log in to EcoStruxure IT as Administrator.

5. Return to SSO configuration in ITE. If the test login was successful, click Verify.
   If the test login was not successful, the SAML configuration is incorrect. Click Not working? Start again.

IMPORTANT: You must successfully test your connection to enable SSO for your email domains.

3. Verify domain ownership

You must verify that you own the domains you specified in the SAML details. There are three ways to verify ownership: DNS TXT, HTML file, or HTML META. The verification method you choose depends on your domain's web host. 

Contact your Customer Success Manager for help verifying your domain ownership if needed.

DNS

1. Go to the home page of your domain and create a DNS TXT record.

2. Copy the TXT content displayed in ITE starting with ecostruxure-it-verification=

3. Return to ITE and click Verify.

   

HTML file

1. Create the file ecostruxure-it-verification.html using the contents diplayed in ITE, and upload it to your domain's website. 
   Your website must be publicly available at the naked domain, with no www or any other subdomain prefix in its URL. Example: https://randomdomain.dk/ecostruxure-it-verification.html 

2. Return to ITE and click Verify.

   

HTML META

1. Add the meta tag displayed in ITE to the <head> section of your website's home page.
   Your website must be publicly available at the naked domain, with no www or any other subdomain prefix in its URL. Example:

   https://randomdomain.dk/ecostruxure-it-verification.html

2. Return to ITE and click Verify.

   

Repeat step 3 to verify all the domains you specified.

Once you have verified all your domains, your SSO configuration is complete. You can return to the SSO page to add and verify additional domains as necessary.

Enable Identity Provider (IdP) Initiated SSO login

Check to allow users to log in to IT Expert from the login page for your organization's identity provider. 
Note: IT Expert uses OIDC as a response protocol.

See Identity Provider (IdP) initiated SSO risks and considerations

Update your SAML SSO certificate or sign-in URL

Click the Edit configuration button to update your SAML SSO sign-in URL or SAML SSO certificate.

Before you make any changes to the configuration, make sure there is at least one Administrator user configured in IT Expert who does not required SSO to log in.

Click Yes to continue.

Update your SAML SSO sign-in URL and SAML SSO certificate as needed.

The expiration date is extracted from the certificate and cannot be edited.

Click Continue.

Test your SAML configuration (see step 2 above) and then verify your domain (see step 3 above) to enable SAML SSO settings.

Reset SSO configuration

Resetting your SSO configuration completely removes all SSO settings in IT Expert.

You must start again at step 1 to reconfigure SSO, including reconfiguring SSO when your SSO certificate has expired.

The URLs and verification files from any previous ITE SSO configuration cannot be reused.

When you reset your SSO configuration, users who are required to use SSO to log in to ITE will no longer have access unless they also have IT Expert user accounts listed in Administration > Users.

[maxstr]

When adding the certificate, I downloaded the PEM file directly from Azure, but it kept saying invalid certificate. I figured out I had to delete the last line for it to be accepted. For example, after the part that says "-----END CERTIFICATE-----", there was a blank line below it that I needed to delete. 

Schneider should automatically trim empty lines because those certificates have a blank line by default

[JLehr]

Hi @maxstr,

Thanks for the feedback. I'll pass it along.

You can provide feedback directly in the IT Expert application, too. Click the Help icon (?) in the upper right corner and then click Feedback.

[JLehr]

Hi @maxstr,

Thanks again for pointing out the spacing issue in the certificate. Engineering will address it shortly.

Best,

Jackie