ToolWatch can be configured to rely on an identity provider as the source of truth for user authentication and authorization. This configuration uses the Security Assertion Markup Language (SAML) standard to exchange identity information between ToolWatch (the service provider) and a configured identity provider. Using an identity provider with ToolWatch can simplify user management and improve security.
Some of the benefits of SAML include:
Improved security
Ease of use
Reduced management and setup needs for system administrators
Reduced waste from time spent entering/re-entering passwords or forgetting passwords
ToolWatch Service Provider Settings
ToolWatch acts as the service provider in the SAML2 SP-Initiated HTTP Redirect Binding flow, and IdP-Initiated login is also supported (it can be enabled per domain claim). The following are ToolWatch's SAML2 service provider configuration attributes:
Attribute | Value |
Entity ID (Identifier) | https://cloud.toolwatch.com/login/sso/saml2/metadata (A custom Entity ID may optionally be specified in ToolWatch's configuration to override this setting. If specified, the custom value will be set as the saml:Issuer in the ToolWatch SAML2 authorization request.) |
Assertion Consumer Service URL (Callback URL, Reply URL) | |
Logout URL |
Identity Provider Settings ToolWatch Needs
ToolWatch requires the following identity provider configuration attributes:
Attribute | Description |
Identity Provider Login URL | ToolWatch will direct AuthnRequests to this URL |
Issuer (Identifier) | Unique name for the identity provider |
Identity Provider Certificate | Public key X.509 corresponding to signed responses from the identity provider |
User Claim Attributes
ToolWatch will read the following attributes from the user claim:
Attribute | Required? | Description |
saml:Subject/saml:NameId | Required | An emailAddress-format NameID is preferred and becomes the ToolWatch username. A non-email NameID is also accepted as long as the user's email is supplied via an attribute (see below). |
User.email; or the ADFS claim URI .../claims/emailaddress; or mail | Used when the NameID is not email-format | The user's email address; becomes the ToolWatch username when the NameID is not an emailAddress-format value. |
first_name; or the ADFS claim URI .../claims/givenname; or User.FirstName; or givenName (tried in that order) | Required for just-in-time user creation | First name of the ToolWatch employee |
last_name; or the ADFS claim URI .../claims/surname; or User.LastName; or sn (tried in that order) | Required for just-in-time user creation | Last name of the ToolWatch employee |
user_role, or https://toolwatch.com/identity/claims/user_role | Optional | Unique user role name in ToolWatch that the user should have authorization for, e.g. "Admin". If a supplied user role name doesn't exist, or is not unique, just-in-time user creation does not happen and the login request is denied. If no user_role claim is supplied — and "require user role claim" is not enabled for the domain and no default role is configured — the just-in-time-created (or newly promoted) user is granted ToolWatch's built-in Admin role. Configure a default role, or require the claim, to avoid unintentionally granting Admin. |
stock_location, or https://toolwatch.com/identity/claims/stock_location | Optional | Unique stock location description in ToolWatch that the user is pinned to, e.g. "Warehouse A". If the stock location description doesn't exist, or is not unique, just-in-time user creation does not happen and the login request is denied. |
org_id, or https://toolwatch.com/identity/claims/org_id | Only required in multi-database scenarios | Unique orgId that the user will be just-in-time created in. Required when the same identity provider is controlling logins across multiple ToolWatch databases, e.g. "TOOL1" |