WebApi Authorization

Overview

The WebApi Authorization section is used to granulate who can access the Controller, Node, and Admin methods. Configure Authorization by adding one or more Providers, using the AppliesTo settings to filter what is affected by the specific Provider.

YAML Layout

Fields

Name

Type

Required

Description

AllowAnonymous

boolean

No, default is True

Set this False to specifically disallow anonymous access to authorization-checked actions.

Providers

Section

No

Create entries in the section to control access to API methods. If no Providers are configured, the API defaults to "allow access to all methods for everyone." Note: The Controller->Start methods will still honor Plan security, even if "everyone" can execute the Start method itself.

Type

string

Yes

Syntax Library:Namespace.ClassName (as with Hander Type declaration)

AppliesTo

Section

No

Used to filter the Providers list at runtime.

AppliesTo.ServerRole

bitmask enumeration

No

Specifies with of the WebApi functions are governed by this Provider. You may combine any of the values as csv: ServerRole: Node, Admin, .... The default value is Universal.

AppliesTo.Topics

string list

No

Adds to the filter for specific API methods/method groups. See below for valid options.

Topics:

Allows execution of /admin/hello/about, which dumps the Synapse.Server.config.yaml and the server file inventory in a json response.

AutoUpdate

Allows starting the AutoUpdate process.

AutoUpdateLogs

Allows AutoUpdate log inspection.

Logs

Allows Synapse.Server log inspection.

Runtime Filtering of Providers Detail

As stated above, omitting a Providers list translates to "allow access to all methods for everyone." Further, omitting a Provider to govern any particular function follows in suit, and access is granted by default. As such, populating the Providers list translates to "this function requires authorization." At runtime, the Authorization provider list is filtered in one of the two patterns below:

ContainsRole( role ) .and. NoTopics()

ContainsRole( role ) .and. ContainsTopic( topic )

Pattern 1: ContainsRole( role ) .and. NoTopics()

Each of the main WebApi entry points supports "global" Authorization, meaning, you can authorize at the Controller, Node, or Admin level, together, or separate. In the following example, the first provider will authorize the Controller and Node, and the second will authorize the Admin interface only.

Pattern 2: ContainsRole( role ) .and. ContainsTopic( topic )

For WebApi methods that advertise a Topic, you may further granulate access with the Topics list. The following example extends the previous example by providing specific access to the Node->Drainstop and Admin->About/AutoUpdate methods. When a topic list is specified, any Provider entries matching Pattern #1 are ignored in favor of those matching Pattern #2.

Note: the runtime engine processes the entire list of matching Providers list, sequentially. If multiple Providers address the same ServerRole/Topic, the engine will process each Provider and ultimately reports the cumulative authorization outcome.

Providers

Synapse.Authorization:WindowsPrincipalProvider

The WindowsPrincipalProvider authorizes against a simple list of domain\username (users) or Active Directory groups in a standard Allowed/Denied pattern, where Denied principals always supersede Allowed principals. As mentioned above, the runtime engine processes the Providers list sequentially and the first Provider to answer with Allow/Deny will terminate processing.

WindowsPrincipalProvider Config Fields

Path to a serialized Users/Groups structure. Changes to this file are detected at runtime, such that Synapse.Server does not require a restart to honor updates.

Users

string lists

No

Two lists, Allowed and Denied of user principals, in the form of domain\username

Groups

string lists

No

Two lists, Allowed and Denied of group principals, in the form of groupname

Note: Both Users and Groups are marked as not required. Omitting Allowed translates to "everyone is allowed," and omitting Denied translates to "no one is denied." Providing an Allowed list translates to "only these principals are allowed, others are implicitly denied." Providing a Denied list explicitly denies named principals and overrides any explicit allows.

Provided

Omitted

Allowed

Explicitly granted access. Others implicitly denied.

"Everyone" implicitly allowed.

Denied

Explicitly denied access. Others implicitly allowed.

"Everyone" implicitly allowed.

In the two examples below, with an explicit Allow, the "Synapse Admins" group is permitted access to the Admin methods. The user "steve" (presumably a member of "Synapse Admins") is explicitly denied access, and any other principals are implicitly denied. For user "steve," both Provider setups produce the same result since all matching Providers are processed. However, for group "Synapse Admins," the second Provider setup also grants access to the Controller and Node methods.

Synapse.Authorization.Suplex:SuplexProvider

The SuplexProvider is nearly identical to the WindowsPrincipalProvider, except instead of sourcing Active Directory for Group information, it sources a Suplex store. Like the WindowsPrincipalProvider, the SuplexProvider authorizes against a simple list of username \ domain\username (users) or Suplex groups in a standard Allowed/Denied pattern, where Denied principals always supersede Allowed principals. As mentioned above, the runtime engine processes the Providers list sequentially and the first Provider to answer with Allow/Deny will terminate processing.