Single Sign-on Authenticator
The ThingworxSSOAuthenticator is used to provision users when single sign-on (SSO) is enabled in ThingWorx. User accounts are created and updated based on attributes retrieved from the identity provider through SAML assertions. Use this authenticator to define default settings for provisioned users, or identify SAML attribute values that are applied to user settings. SAML provisioning does not delete user accounts. For that functionality, refer to SCIM provisioning.
Prerequisites
1. SSO must be enabled in ThingWorx. For more information, see Single Sign-on Authentication.
2. Map attributes in the PingFederate policy contract.
As part of the SSO configuration, an authorization server (PingFederate) is deployed and configured to redirect SAML authentication requests to your identity provider. You create an SP Connection in PingFederate to which ThingWorx sends its SAML authentication requests. A policy contract is the mechanism that PingFederate uses to pass assertion attributes from the identity provider to the service provider (ThingWorx). Any attributes identified in the following configuration tables will need to be listed in the policy contract in PingFederate so they can be passed between connections.
For more information, refer to the following:
◦ PingFederate Documentation: Bridging an IdP to an SP https://docs.pingidentity.com/bundle/pingfederate-100/page/ffk1564002971738.html
◦ PingFederate Documentation: Federation hub and authentication policy contracts https://docs.pingidentity.com/bundle/pingfederate-100/page/ope1564002971971.html
The options in the following configuration tables allow you to specify the behavior of the authenticator.
User Provisioning
|
User Creation Enabled
|
Select to allow user accounts to be created in ThingWorx based on credentials retrieved from the authorization server. If a user attempts to log in to ThingWorx, but a ThingWorx user account has not been created, then this setting allows the creation of the ThingWorx user account based on the user data stored in the identity provider.
|
|
User Modification Enabled
|
Select to allow the modification of user accounts that exist in ThingWorx. This is important to allow future updates to accounts during subsequent login events after the initial login when the user was created to synchronize the ThingWorx user data with the user account data in the identity provider.
|
|
All Credential Attributes Must be Provisioned
|
If enabled, all of the credential attributes returned by the Identity Provider must be consumed (applied to the user). If any are not consumed, then the user is not created/updated and the login fails.
This option is not selected by default.
|
|
Terminate User Sessions On Authenticator Change
|
If enabled, all active sessions for provisioned users will be terminated when the ThingWorx SSO Authenticator configuration is saved.
This does not apply to the users specified in the User Provisioning Exclusion List.
This option is not selected by default.
|
User Provisioning Exclusion List
Specify any users that should be excluded from the User Defaults configuration below.
 |
The users are added to this list by default. If you attempt to remove these users, they will be automatically re-added upon refreshing the page.
• ThingWorx Administrator
• SuperUser
• System user
|
User Defaults
These default attributes will be applied to all users except for those added to the User Provisioning Exclusion List. These attributes are applied at the time the user logs in.
|
Description
|
Enter a description you want to use for users that are provisioned. For example, you may wish to note that a user account has been created through auto-provisioning.
|
|
Mashup
|
Specify the default Home Mashup that provisioned users will see upon login.
|
|
Mobile Mashup
|
Specify the default Mobile Mashup that provisioned users will see upon login.
|
|
Tags
|
Specify the default tags to apply to provisioned users. This list of tags will override any existing tags for user accounts that already exist and are being updated.
|
User Identity Provider Settings
Instead of applying the settings defined in the User Defaults table above, use this table to identify the attributes retrieved from the identity provider that should be applied to the user’s setting. In this table, you specify attribute keys for user attributes that are returned in the SAML assertion from the identity provider. The value that is returned for that attribute key will be applied to the user’s setting. Entries that are defined in this table will override the default settings specified in the User Defaults table.
|
Description
|
Enter an attribute key that corresponds to the attribute value that should be applied as the description.
|
|
Home Mashup
|
Enter an attribute key that corresponds to the attribute value that should be used to determine the home mashup.
|
|
Mobile Mashup
|
Enter an attribute key that corresponds to the attribute value that should be used to determine the mobile mashup.
|
|
Tags
|
Enter an attribute key that corresponds to the attribute value that should be used to determine what tags are applied to the user.
|
|
Groups
|
Enter an attribute key that corresponds to the attribute value that should be used to determine the ThingWorx groups to which the provisioned user is added to.
|
Provisioned User’s Default Groups
Specify the groups to which the auto-provisioned users should be added to. This list of groups will override any existing group memberships.
Identity Provider Group Mappings
This table maps the IdP group name to the corresponding ThingWorx group name.
For example, you might want the provisioned group to have a different name in ThingWorx than is given in the IdP. Once you have mapped the names, any changes made to the group in the IdP are reflected in the mapped ThingWorx group.
User Extension Provision Names
This table is used to set the values for user extension properties. For more information about these properties, see User.
There are three columns for each table entry:
• Property Name identifies the user extension property
• Default Value allows you to specify a value that will be applied to the property by default when a user account is provisioned.
• Identity Provider Attribute allows you to specify a custom attribute that is returned in the SAML assertion. The value of the returned attribute will be applied as the property value. If this field is defined, it overrides the setting in Default Value.
|
|
If you are also using SCIM provisioning, then you should use this table to ensure that there is a SAML assertion for any user extension attribute values that are returned from the authorization server or IdP through a SCIM schema attribute. For more information, see Provisioning.
|
When SSO is enabled in ThingWorx, the ThingworxSSOAuthenticator is enabled and is the default authenticator. If SSO is not enabled in ThingWorx, then the authenticator is disabled. The following login authenticators are disabled when SSO is enabled:
• ThingworxAppKeyAuthenticator
• ThingworxBasicAuthenticator
• ThingworxFormAuthenticator
• ThingworxHttpBasicAuthenticator
Note that the following authenticators have a configurable option to enable them. However, SSO overrides that option, and they are always disabled when SSO is enabled.
• ThingworxMobileAuthorizationAuthenticator
• ThingworxMobileTokenAuthenticator
• Custom authenticators
The following table provides information about user state changes in ThingWorx, as a result of the options selected in the ThingworxSSOAuthenticator and their state in the authorization server or IdP at the time they logged in. User states are in the authorization server or IdP are not changed in these scenarios; only their state in ThingWorx is affected. Items appended with [Primary] are the primary factors that affect the state of the user in ThingWorx after login.
|
User State in AS or IdP
|
User State in ThingWorx Prior to Login
|
ThingworxSSOAuthenticator Options
|
User State in ThingWorx After Login
|
|---|---|---|---|
|
Does not exist
|
Does not exist
|
Any configuration
|
• Does not exist
• Cannot be used to log in
|
|
Does not exist
|
• Exists (manually created by Thingworx Administrator)
• [Primary] Password was set and resides in Thingworx
|
• User Provisioning Creation Enabled
• User Provisioning Modification Enabled
• [Primary] Listed in User Provisioning Exclusion List
|
• Exists
• Is not modified
• Cannot be used to log in
|
|
Does not exist
|
• Exists (manually created by Thingworx Administrator)
• [Primary] Password was not set or does not reside in Thingworx
|
• User Provisioning Creation Enabled
• User Provisioning Modification Enabled
• [Primary] Listed in User Provisioning Exclusion List
|
• Exists
• Is not modified
• Cannot be used to log in
|
|
Does not exist
|
Exists (manually created by Thingworx Administrator)
|
• User Provisioning Creation Enabled
• User Provisioning Modification Enabled
• [Primary] Not listed in User Provisioning Exclusion List
|
• Exists
• Is not modified
• Cannot be used to log in
|
|
• Exists
• [Primary] Disabled
|
Does not exist
|
• User Provisioning Creation Enabled
• User Provisioning Modification Enabled
• Not listed in User Provisioning Exclusion List
|
• Does not exist
• Cannot be used to log in
|
|
• Exists
• [Primary] Locked
|
Does not exist
|
• User Provisioning Creation Enabled
• User Provisioning Modification Enabled
• Not listed in User Provisioning Exclusion List
|
• Does not exist
• Cannot be used to log in
|
|
Exists
|
Does not exist
|
• [Primary] User Provisioning Creation Disabled
• User Provisioning Modification Enabled
• Not listed in User Provisioning Exclusion List
|
• Does not exist
• Cannot be used to log in
|
|
Exists
|
Does not exist
|
• [Primary] User Provisioning Creation Enabled
• User Provisioning Modification Enabled
• [Primary] Not listed in User Provisioning Exclusion List
|
• Exists (created)
• Added as a member to mapped Groups
• Default user settings added
• Can be used to log in
|
|
Exists
|
Exists
|
• User Provisioning Creation Enabled
• [Primary] User Provisioning Modification Enabled
• [Primary] Not listed in User Provisioning Exclusion List
• [Primary] User default settings configured
|
• User is modified
• Added/removed as a member to mapped Groups
• Default users settings added
• Can be used to log in
|
|
Exists
|
Exists
|
• User Provisioning Creation Enabled
• [Primary] User Provisioning Modification Enabled
• [Primary] Listed in User Provisioning Exclusion List
• [Primary] User default settings configured
|
• User is not modified
• Can be used to log in
|