Processing Settings

The SETTINGS sub-tab provides configuration for special virtual service's settings grouped by different settings areas.

Identities

The Identities section enables the configuration of a virtual service's advanced identities processing rules. These configuration options come in two groups -- Inbound identities processing and Outbound identities processing.

Inbound Identities

The Inbound identities section configures authentication options and identities mapping options for inbound client identities.

Username/Password Authentication group configures authentication options when inbound identities are represented by a Username and Password. Available options are:

a. Windows. This option instructs the virtual service to authenticate Username/Password client identities against Active Directory or the local machine Windows Users store. Once identities are authenticated, they will be mapped to Windows identities that can be used in the Sentinet Access Rules for fine-grained authorizations.

b. None default option. This option instructs the virtual service not to use any explicitly configured authentication store, and to pass Username/Password "as is" to the Sentinet Authorization Engine, where client credentials might be authenticated and authorized using Username/Password Access Rule Expressions (see the Access Rule Graphical Designer chapter). Effectively, this option turns the Sentinet Repository database into an identity store (if Access Rule Expressions are eventually configured with the virtual service's Access Rules and Access Control).

c. Custom. This option provides the Sentinet extensibility point to use any custom or third-party Identity Store, and to implement custom mapping for Username/Password identities. Developers must implement their own WIF Username token handler and configure it in the Sentinet Node web.config file (see https://msdn.microsoft.com/en-us/library/ee517261.aspx for more details on how to implement and configure custom Username token handlers). A Sentinet Node will switch to the custom Username/Password validation configured in the Node's web.config file if a virtual service is configured with the Custom Username/Password Authentication option.
Map to Windows group determines whether the inbound client identity must be automatically mapped to a Windows Identity (enabling these options may require additional configuration of an Active Directory).

a. X.509 Certificate. Enabling this option will attempt mapping an inbound X.509 certificate to a Windows Active Directory account.

b. SAML (UPN). Enabling this option will attempt mapping a SAML-provided UPN claim to a Windows Active Directory account.

Outbound Identities

The Outbound identities section configures client identities' pass-through options when the identity of the original caller is passed through the virtual service to the business service.

Enable Windows identity pass-through. When this option is turned on, a Sentinet Node will impersonate received or mapped inbound Windows identity to make outbound calls. Enabling this option requires mapping of X.509 and SAML (UPN) identities to be turned on (see Inbound Identities above). Also, all virtual service inbound endpoints are required to either receive or map inbound identities to Windows identities.

Note

If a Windows Identity is explicitly provided in the inbound message, it must have its Allowed Impersonation Level set to Impersonation or Delegation.
Enable Username/Password credentials pass-through. This option configures inbound Username/Password credentials to be used to make outbound calls.
Enable internal Security Token Service (STS) for claims issuance. When this option is turned on, a virtual service will use Sentinet's internal Security Token Service (STS) for outbound endpoints that are configured with WS-Federation security or OAuth security for REST APIs. Unlike real STS servers, Sentinet's internal STS does not provide the actual STS web interfaces that can process requests for STS tokens. Instead, the Sentinet Node runtime generates SAML or JWT OAuth tokens "on-the-fly" out of all known inbound claims. Effectively, a Sentinet Node executes as an STS without the overhead and additional network latencies associated with external STS servers. All inbound identities will be automatically converted into SAML claims or JWT token claims and delivered to the physical service configured with WS-Federation or OAuth security. Sentinet's internal STS is a unique feature that provides identities with pass-through capabilities regardless of which types of client identities the applications use. Sentinet's internal STS is available for both SOAP services and REST APIs. Sentinet will automatically generate outbound SAML or JWT token depending on the policy the outbound endpoint is configured with, WS-Federation for SOAP or OAuth for REST. Note: if the virtual service is SOAP, then it can be configured with only SAML, because virtual SOAP services cannot virtualize REST APIs.

SAML tokens are always signed by the hosting Node's X.509 certificate, whereas JWT tokens can also be signed with the known HMAC Shared Secret. Known or desired HMAC Shared Secret can be entered directly in the configuration screen or a new Shared Secret can be generated by Sentinet.

Figure. Example of a virtual REST service configured with the internal STS feature.

Figure. Example of Sentinet Node as a SAML/OAuth claims issuer (internal STS/OAuth server).

Pass-through HTTP Headers

Pass-through HTTP Headers section specifies which HTTP header should be passed through by the Sentinet Nodes. The setting is most often used with REST APIs, even though it can also be used to pass through HTTP headers for SOAP services, which are bound to HTTP(S) protocols. Header names in the Request Headers and Response Headers fields must be separated by a comma, semicolon, asterisk or space. By default, virtual SOAP services do not have Pass-through headers configured, while virtual REST services have Content-Type header configured for both Request and Response headers. For example, configuring this field with Content-Type, User-Agent, MyHeader will ensure that these three headers will be passed through with their values when present in the inbound request.

Note

If an HTTP Header is explicitly defined for physical and its virtual service’s responses (the same HTTP header shows in the Swagger for the physical and its virtual service), then that header will be treated as response’s pass-through HTTP header.

Internal Errors

Internal Errors section (available for virtual REST services only) defines HTTP error codes that will be generated by the virtual service when the virtual service itself issues an error (as opposed to an error generated by the physical service).

Custom Error Message fields provide space to specify custom error messages (replacement for the default Sentinet error messages) for:

Default "Access is Denied" error message generated by the Sentinet Access Control engine when access to a virtual service is denied.
Default error message that is generated, when a request sent to a virtual service cannot be mapped to any existing service operation (request does not match any available REST service's operation definition).

If Custom error message fields are empty, Sentinet will generate default error messages.

If a Custom error handler section defines a custom .NET Assembly and .NET class (Type), then your custom code will get a chance to overwrite any other default or statically configured custom error message.

Custom .NET class must implement IWebErrorHandler interface:

namespace Nevatech.Vsb.Repository.Services.Web
{
  public interface IWebErrorHandler
  {
      void HandleError(WebErrorHandlerContext context);
  }
}

Compiled custom .NET assembly, which implements custom error handler must be placed on the Sentinet Node server machine(s) either in the bin folder of the Node application (create bin folder if it does not exist), or it can be registered in machine’s GAC.

Sentinet is shipped with the sample Visual Studio .NET project, CustomErrorHandler, which demonstrates implementation of a custom error handler.

Figure. Example of a custom error handler configured with the virtual service.

Faults (Application Errors)

Faults (Application Errors) section (available for virtual REST services only) defines HTTP status codes that will treat REST response messages as REST Faults (Application Errors) as opposed to communication or non-application related errors. By default, all status codes starting from 400 onwards are treated as non-Fault errors, all codes lower than 400 are treated as successful. You can also add additional conditions for your custom HTTP status codes to further control Application Faults (for example, you may want to treat HTTP 200 status codes as Application Fault if response message body contains the word error).

Figure. Condition assignment to the custom HTTP status code(s).

CORS (Cross-Origin Resource Sharing) section (available for virtual REST services only) provides configuration to enable REST service with support for CORS (see CORS specification for the details of each property provided in this section).

Important

Current version of the Sentinet product uses browser client-side script to support trying out REST APIs from the Developer Portal. Try It Out feature of the Developer Portal requires virtual service to be configured with enabled CORS. To support Try It Out feature you can enable CORS with default (*) values, or limit Allowed Origins value to the address of the Developer Portal, for example: https://SentinetDevPortalServer.

Advanced

Advanced section has two specific properties:

Always new outbound connections. In some specific scenarios, a Sentinet Node might be instructed to always use a new outbound connection for virtual service outbound calls rather than trying to use an existing cached network connection, which may not be valid (consider this option only for stateful protocols).
Published to Microsoft Azure Service Bus Registry. This setting is applicable for virtual services with Microsoft Azure Service Bus endpoint(s) that must be published in the Microsoft Azure Service Bus Registry.

Behavior

The Behavior processing section provides configuration of the virtual service specific WCF behaviors. These are the behaviors that affect the entire virtual service regardless of service operation or service endpoint called. They provide additional WCF-specific extensibility points for remote and dynamic configuration of the standard and custom WCF service behaviors (see https://msdn.microsoft.com/en-us/library/system.servicemodel.servicebehaviorattribute.aspx and https://msdn.microsoft.com/en-us/library/ms751453.aspx for more details on WCF service behaviors). Sentinet service behaviors can be added, removed and modified similarly to how virtual service inbound and outbound endpoints can be configured with WCF standard and custom endpoint behaviors (see Outbound Endpoint -> Behavior chapter for more details).