SAML SSO

When enabled then SAML SSO is displayed as an alternate login method at SpectX Server login screen. Choosing this method starts service provider-initiated SAML 2.0 single sign-on flow by issuing an explicit authentication request to the identity provider (e.g. ADFS), and finally asserting authentication response.

User identity (SAML NameID attribute from authentication response) must be registered as SpectX user to determine the user rights upon successful authentication. If SpectX Server does not find matching user in its user database and automatic user account creation is disabled then the authentication flow falls back to default authentication scheme via login screen.

SpectX Server can be configured to represent multiple different SAML service providers to support environments with more than one SAML identity provider.

Warning

To protect the confidentiality of user credentials the communication must be protected by TLS.

Configuring Authentication

To enable SAML SSO authentication in SpectX Server, you have to first specify a comma-separated list of string identifiers for SAML service provider entities the SpectX Server must represent in configuration parameter wgui.samlAuth.ids. For environments requiring only one service provider instance, the list contains only one identifier. Syntactically, each identifier is allowed to contain only digits, Latin letters, dot and dash characters. These identifiers are used for:

  • distinguishing between enabled SAML service providers, and composing their assertion and metadata URLs
  • composing the SpectX user name. If the NameID value of the SAML authentication response processed by the corresponding service provider does not contain ‘@’ symbol, the value of the identifier is appended to the NameID value.

For each identifier <id>, the following configuration parameters must be specified to enable corresponding SAML service provider interface:

  • wgui.samlAuth.<id>.spEntityId - the globally unique SAML SP EntityId (Relying party trust identifier in ADFS). SAML specification recommends it to be a SP URL containing its own domain name to identify itself. You may specify an URL of the SpectX Server WebUI and append the value of identifier to it.

  • wgui.samlAuth.<id>.idpSsoServiceUrl - URL of SAML identity provider single sign-on service. For ADFS, it is typically https://<adfs-host>/adfs/ls/.

  • wgui.samlAuth.<id>.idpTokenSigningCertFile - Path to file with identity provider’s token signing certificate. Both DER and BER formats are supported.

  • wgui.samlAuth.<id>.redirectUri - The fully qualified URI of your SpectX Server instance or its frontend server.

Other optional parameters are:

  • wgui.samlAuth.<id>.name - the label of authentication scheme displayed on Login screen for this type of authentication (default is “as <id> user”)

  • wgui.samlAuth.<id>.autoCreateAccount - boolean setting enabling automatic creation of user accounts in the SpectX Server user database when they first log into SpectX Server with given authentication method. This feature is off by default. If it is on, then user’s full name is obtained from the following user metadata attributes (“claims”) of a SAML authentication response:

    • either Name attribute, if present
    • or by combining values of givenName and surName attributes, if present.

    Warning

    When automatic user account creation is enabled, every authenticated user can log in to SpectX Server. It is highly recommended to enforce authorization of access to SpectX Server.

  • wgui.samlAuth.<id>.autoCreateApiKey - boolean setting enabling automatic creation of API key for user accounts which get created automatically when they first log into SpectX Server with given authentication method. The setting is ignored if wgui.samlAuth.<id>.autoCreateAccount is not set to true. The default value for this setting is false.

  • wgui.samlAuth.<id>.errRedirectPeriod - Time period for displaying error message regarding failed SAML authentication before redirecting user’s browser to login page. Default value is 5s. Negative value disables automatic redirection.

Configuring Authorization

When automatic user account creation is configured, each user successfully authenticated by identity provider can potentially log in to SpectX Server. To facilitate additional access control to SpectX Server you can configure list of group names which will be matched against values of Group metadata attribute (“claim”) of a SAML authentication response. If at least one match is found, the user will be granted access to SpectX Server and will be denied otherwise.

To enable claim group matching, you have to specify the following configuration parameter:

  • wgui.samlAuth.<id>.allowedGroups - comma-separated list of group names to be matched against Group metadata attribute values of the SAML authentication response. Note that each separate name cannot contain commas, and any backslash (‘\’) symbol in it should be escaped by another backslash. Matching is case-sensitive.

Example

Example SpectX Server configuration excerpt, provided that the company has 2 ADFS instances in separate regions, each authenticating its users which access SpectX’s frontend server at URL https://spectx.int.company.net/, and get access to it only if they are members of “SpectX Users” group in own domain:

...
    wgui.samlAuth.ids=Asia,Europe

    wgui.samlAuth.Asia.spEntityId=https://spectx.int.company.net/Asia
    wgui.samlAuth.Asia.redirectUri=https://spectx.int.company.net/
    wgui.samlAuth.Asia.idpSsoServiceUrl=https://dc.asia.int.company.net/adfs/ls/
    wgui.samlAuth.Asia.idpTokenSigningCertFile=${SPECTX_HOME}/conf/dc.asia.int.company.net.signing.cer
    wgui.samlAuth.Asia.allowedGroups=asia\\SpectX Users

    wgui.samlAuth.Europe.spEntityId=https://spectx.int.company.net/Europe
    wgui.samlAuth.Europe.redirectUri=https://spectx.int.company.net/
    wgui.samlAuth.Europe.idpSsoServiceUrl=https://dc.europe.int.company.net/adfs/ls/
    wgui.samlAuth.Europe.idpTokenSigningCertFile=${SPECTX_HOME}/conf/dc.europe.int.company.net.signing.cer
    wgui.samlAuth.Europe.allowedGroups=europe\\SpectX Users

Once the configuration is set, restart the SpectX server and you’re done. Now you have to register configured service providers at the identity provider side. For that, the following two parameters will be required to know for each provider:

  • SAML Assertion Consumer Endpoint URL. Technically, it is composed by SpectX Server for each provider as follows:

    <redirectUri>/AUTH/v1.0/saml/login/<id>.

    This can be obtained by finding corresponding “SAML Auth#<id> spAssertionUrl” in the SpectX Server StatusPage.

  • service provider EntityId, which is the value specified for wgui.samlAuth.<id>.spEntityId parameter in configuration.

Alternatively, these settings can be imported into the identity provider configuration using a metadata URL, which is composed as

<redirectUri>/AUTH/v1.0/saml/metadata/<id>.

Another method to get it is to find entry “SAML Auth#<id> spMetadataUrl” in the System Status page Effective Settings tab (accessible for users with Administrator role).