Supported Authentication Types and Configurations

Overview

Synapse supports many mechanisms to identify whether a client is eligible to access a resource. There are three places authentication is applied in the normal flow of a Synapse call :

  • Client to Controller : This is typically the identify of the calling user or application, except when "Anonymous" authentication is allowed.
  • Controller to Node : Under normal setup, this would be the credentials under which the Controller is running (service account, LocalSystem, etc...). To use the credentails of the calling user or application, enable impersonation in the server config file.
  • Node to Controller : Under normal setup, this would be the credentials under which the Node is running (service account, LocalSystem, etc...). To use the credentails of the calling user or application, enable impersonation in the server config file.

This document assumes that impersonation is set to "false" in the server config file and that authentication between the Controller and Node uses the credentails under which each service is running. To see how this changes when using impersonation, please click here.

Supported Types

The Synapse Server, Controller and Node support the following authentication types :

  • Anonymous
  • Basic
  • Ntlm
  • IntegratedWindowsAuthentication
  • Negotiate

Valid Configurations

Certain combinations of authentication types between the Controller and Node will not allow Synapse to function as expected, mostly because the authentication required by one isn't sufficient to meet the authentication needs of the other. Below is a table defining whether the combination of Authentication schemes for the Controller (Vertical) and the Node (Horizontal) will allow normal Synapse functionality.

Controller | Node >>>
vvv		 Anonymous Basic Integrated Ntlm Negotiate
Anonymous Yes No Yes Yes Yes
Basic Yes Yes No No No
Integrated Yes No Yes Yes Yes
Ntlm Yes No Yes Yes Yes
Negotiate Yes No Yes Yes Yes

Defining Inbound Authentication Types

The authentication type of the Controller or Node is specified in the server config file under the WebApi > Authentication section. Currently, only Basic authentication requires the "Config" section to be present.

WebApi:
  Host: localhost
  Port: 1370
  IsSecure: false
  UseImpersonation: false
  Authentication:
    Scheme: Basic
    Config: 
      LdapRoot: LDAP://dc=sandbox,dc=local
      Domain: SANDBOX

Explicitly Defining Outbound Authentication Type

By default, the authentication type received by the Controller will be used to communicate with the Node (and vice-versa) or will be automatically translated to the required type. This automatic translation of authentication types does not apply to the "Basic" authentication type however. If both the Controller and Node are setup for Basic authentication, Synapse Server will simply pass the header received from the client to the Node and then back to the Controller when sending status back.

However, if the Controller receives Basic authentication, but the node is expecting Ntlm authentication, you would need to tell SynapseServer to not send the Basic header information forward, but use Ntlm instead. In this case, you would need to explicitly indicate what type of authentication to use when communicating between the Controller and Node by using the following fields in the server config file :

Controller To Node Authentication Scheme

Use the "NodeAuthenticationScheme" field under the Controller section.

Controller:
  NodeUrl: http://localhost:1375/synapse/node
  NodeAuthenticationScheme: Ntlm
  SignPlan: false
  Assemblies: 
  Dal:
    Type: Synapse.Controller.Dal.FileSystem:FileSystemDal
    LdapRoot: 
    Config:
      PlanFolderPath: Plans
      HistoryFolderPath: History
      ProcessPlansOnSingleton: false
      ProcessActionsOnSingleton: true
      Security:
        FilePath: Security
        IsRequired: false
        ValidateSignature: false
        SignaturePublicKeyFile: 
        GlobalExternalGroupsCsv: Everyone

Node To Controller Authentication Scheme

Use the "ControllerAuthenticationScheme" field under the Node section.

Node:
  MaxServerThreads: 0
  AuditLogRootPath: .\Logs
  Log4NetConversionPattern: '%d{ISO8601}|%-5p|(%t)|%m%n'
  SerializeResultPlan: true
  ValidatePlanSignature: false
  ControllerUrl: http://localhost:1370/synapse/execute
  ControllerAuthenticationScheme: Ntlm

Use Case

This is mostly used in the case where the Controller is setup to use either Basic or Ntlm authentication, but the Node is Ntlm only. When the Controller receives Basic, you need to tell the SynapseServer to use Ntlm instead of passing the Basic header through to the Node.

Allowing Multiple Authentication Types

Multiple authentication types are supported on the same port for the Controller and Node, allowing the client to supply any valid authentcation type when calling Synapse Server. Multiple authentication schemes are specified in the server config file by placing a comma-seperated list of supported authentication types in the Scheme field of the WebApi > Authentication element.

WebApi:
  Host: localhost
  Port: 1370
  IsSecure: false
  UseImpersonation: true
  Authentication:
    Scheme: Basic, Ntlm
    Config: 
      LdapRoot: LDAP://dc=sandbox,dc=local
      Domain: SANDBOX

Common Configurations

For each scenario below, assume the following setup:

  • User : The user "SANDBOX\guy" will be calling Synapse Controller to start execution of a plan.
  • Controller : The Controller service is running under the credentails "SANDBOX\synapse-controller"
  • Node : The Node service is running under the credentails "SANDBOX\synapse-node"

Also, each scenario below assumes impersonation is set to false. To see how each scenario below would differ with user impersonation enabled, click here.

Simple Windows Authentication

Windows Authentication, No Impersonation

The Controller and Node both accept a single authentcation type of IntegratedWindowsAuthentication, Ntlm or Negotiate.

  1. Client passes user's (SANDBOX\guy) credentials to Controller.
  2. Controller passes plan to Node using the Controller service RunAs credentails (SANDBOX\synapse-controller).
  3. Node executes handlers using the Node service RunAs credentials. (SANDBOX\synapse-node).
  4. Node sends status updates to Controller using the Node service RunAs credentials (SANDBOX\synapse-node).

Server Config File Setup Details

Synapse Server Config Value
WebApi > Authentication > Scheme (Controller) IntegratedWindowsAuthentication
WebApi > Authentication > Scheme (Node) IntegratedWindowsAuthentication
Controller > NodeAuthenticationScheme Empty
Node > ControllerAuthenticationScheme Empty
WebApi > UseImpersonation (Controller) false
WebApi > UseImpersonation (Node) false

No Authentication

No Authentication, No Impersonation

This is where the controller and node are open to the world.

  1. Client passes no credentials to Controller.
  2. Controller passes plan to Node with no credentials.
  3. Node executes handlers using the Node service RunAs credentials. (SANDBOX\synapse-node).
  4. Node sends status updates to Controller with no credentials.

Server Config File Setup Details

Synapse Server Config Value
WebApi > Authentication > Scheme (Controller) Anonymous
WebApi > Authentication > Scheme (Node) Anonymous
Controller > NodeAuthenticationScheme Empty
Node > ControllerAuthenticationScheme Empty
WebApi > UseImpersonation (Controller) false
WebApi > UseImpersonation (Node) false

Authentication on Controller Only

Authentication on Controller Only, No Impersonation

This is where the controller has Windows Authentication set (Ntlm, Negotiate, or IntegratedWindowsAuthentication) but the node is running with no authentication. The key thing to remember here is that if you don't have "SignPlan" set to true in the Controller, and "ValidatePlanSignature" set to true in the node, users could bypass the Controller and execute plans directly if they knew the URL, without any authentication.

  1. Client passes user's (SANDBOX\guy) credentials to Controller.
  2. Controller passes plan to Node with no credentials.
  3. Node executes handlers using the Node service RunAs credentials. (SANDBOX\synapse-node).
  4. Node sends status updates to Controller using the Node service RunAs credentials (SANDBOX\synapse-node).

Server Config File Setup Details

Synapse Server Config Value
WebApi > Authentication > Scheme (Controller) Ntlm
WebApi > Authentication > Scheme (Node) Anonymous
Controller > NodeAuthenticationScheme Empty
Node > ControllerAuthenticationScheme Empty
WebApi > UseImpersonation (Controller) false
WebApi > UseImpersonation (Node) false

Multi-Authentication on Controller, Windows Authentication on Node

Multi Controller, Ntlm Node, No Impersonation

This allows both Basic and Windows Authentication (Ntlm, Negotiate, or IntegratedWindowsAuthentication) to the Controller, but enforces Windows Authentication on the Node. This setup is used to support applications that don't support sending Windows credentails in their web calls. Warning : Basic authentication is not secure on its own. The username and password are simply Base64 encoded in the Request header. This should only be used over a secure connection.

  1. Client passes user's (SANDBOX\guy) credentials to Controller either via Basic or Ntlm authentication.
  2. Controller passes plan to Node using the Controller service RunAs credentails via Ntlm authentication (SANDBOX\synapse-controller).
  3. Node executes handlers using the Node service RunAs credentials. (SANDBOX\synapse-node).
  4. Node sends status updates to Controller using the Node service RunAs credentails via Ntlm authentication (SANDBOX\synapse-node).

Server Config File Setup Details

Synapse Server Config Value
WebApi > Authentication > Scheme (Controller) Ntlm, Basic
WebApi > Authentication > Scheme (Node) Ntlm
Controller > NodeAuthenticationScheme Ntlm
Node > ControllerAuthenticationScheme Ntlm
WebApi > UseImpersonation (Controller) false
WebApi > UseImpersonation (Node) false