secmanctl

The command line tool secmanctl helps to manage ArcGIS Server access policies for service protected by security.manager NEXT.

Usage

$ secmanctl <command> [options]

secmanctl has the following commands:

login: Authenticate to an ArcGIS host and generate a token
apply: Set policies for an ArcGIS Server service
sync: Synchronize policies for multiple ArcGIS Server services based on a local folder
groups: Show ArcGIS Enterprise groups
help: Displays the help

Global options

All commands support the following global options:

--version

Prints the version of the secmanctl command line interface.

--debug

Can be used for error analysis as follows:

In case of an error, detailed trace information is displayed in the console.
In addition, a log file is generated, which contains further information for error analysis. This log file will be created in a temporary folder. The path of the newly created file is printed into the output of the command.

--insecure

Allows to connect to HTTPS endpoints using certificates that are not issued by a trusted CA.

-v, --verbose

Defines the level of verbosity of the process output.

The option can be used multiple times in order to increase the amount of the output.

If the option is omitted, then a command provides only important information.
If the option is used once via -v or --verbose, a command writes more details into the output.
If the option is used twice via -vv or --verbose --verbose, the level of verbosity is set to its highest level.

--help

Prints usage information for a command (secmanctl <command> --help) or for the tool itself (secmanctl --help).

Commands

`login`

Requests an authentication token from an ArcGIS Server. This token is usually needed for the execution of the commands apply, sync, and groups.

To get an authentication token from the ArcGIS Server, you have to provide username and password. This can be done in one of the following ways:

Non-interactive login: Username and password can be provided through the options --username and --password (or the corresponding short form).
Interactive login: If these two parameters are missing, the command is executed in an interactive mode in which the user is prompted to enter these two parameters.
Reading the password from stdin: In addition to that, the password could also be read from the stdin stream. For example, the password can be passed to the login command call using the pipe operator.

If the option --plain is given, the output of this command is reduced to the received token value. This can be very useful in an automated scenario where, for example, the token value needs to be stored in a variable.

Accounts configured to use multi-factor authentication (MFA) are currently not supported. We recommend signing in with an account that is not using MFA or signing in as the primary site administrator. If the primary site administrator account is used, some functions that rely on portal authentication will not be available (such as secmanctl groups).

Usage

$ secmanctl login [options]

Example: Non-interactive login

$ secmanctl login -d https://gis.example.com:6443/arcgis -u adminuser -p ./secret.txt
Login successful.
Authenticated against: https://gis.example.com/portal
Valid until:           2020-10-21T11:08:21.843Z
Requires SSL:          Yes

8cq4PACs9UaroGVLnqkfJCU2BEBHFXOpd518Hbggb31kL7l6Fjhx974oCQYwjLnj0hdsEfTGKKFJLUi-KFqiArfGevUMN8EJnAnswZuZwFn3wIbYqfY9D1Jmjy_8gZOTfl_HzL3u5cSVu5AdunxPsVdBudqqSgJmE-O23jTCHhI.

Example: Interactive login

$ secmanctl login -d https://gis.example.com:6443/arcgis
Enter username: admin
Enter password: **********
...

Example: Password from `stdin`

$ ./get-password | secmanctl login -u admin -p - -d https://gis.example.com:6443/arcgis
Login successful.
Authenticated against: https://gis.example.com/portal
...

Options

-d, --server-url <server-url>: ArcGIS Server base URL.

Used by secmanctl to request an authentication token. If the ArcGIS Server is federated with an ArcGIS Portal, then secmanctl will authenticate to that portal instead.

Example: https://gis.example.com:6443/arcgis
-u, --username <username>: Username of a user account to generate the token for.

Specify the username of a user with administrative permissions. Otherwise, the token will not be accepted when executing any other secmanctl command.
--iwa: Activates the support for Integrated Windows Authentication (IWA).

The Windows account is used to authenticate against ArcGIS Enterprise portal or ArcGIS Server. When using an unfederated ArcGIS Server with IWA, the login command is not needed.
-p, --password <password-file>: Path to a text file (encoded as ASCII or UTF-8) containing the user password as the first line.
-e, --expires <minutes> (optional): Duration in minutes that the generated token shall be valid for.

The maximum value can be restricted by server (or portal) settings.

Default: 60
--plain (optional): Only print the token value and suppress all other output on the standard output stream.

`apply`

Sets a policies JSON file for a specified map service on an ArcGIS Server. If security.manager NEXT is not yet activated for this service, it will be active afterwards.

With the --dry option given, the command does not apply any changes to the ArcGIS Server. Instead, the command execution is simulated and changes which would be applied without the --dry option are printed to the output of this command.

You could also use the sync command in combination with the --service option in order to apply changes to a single service.

Usage

$ secmanctl apply [options]

Example

$ secmanctl apply -i policy.json -d https://gis.example.com:6443/arcgis -s water/wells -t MghzyNeWubQtTgZfMQTx8rasda.. --dry -vv

Options

-i, --input-file <file>

Path to the policy input file that secmanctl should upload.

Use - (dash) to read from stdin.

Example: policies/policy.json

-d, --server-url <server-url>

ArcGIS Server base URL.

This URL shall allow access to the ArcGIS Server Administrator Directory (/arcgis/admin). When using Integrated Windows Authentication, the Web Adaptor URL has to be used.

Example: https://gis.example.com:6443/arcgis

-s, --service [<servicefolder>/]<servicename>

Folder (optional) and name of the ArcGIS Server service the policy file will be applied to.

Examples: water/wells or SampleWorldCities

-t, --token <token>

An ArcGIS admin user token, used by the tool, to authenticate at ArcGIS Server Administration Directory.
When using an unfederated ArcGIS Server with IWA, no token is needed.

--iwa

Activates the support for Integrated Windows Authentication (IWA).

The Windows account is used to authenticate against ArcGIS Server.

-f, --folder <path> (optional)

Path to a policies working directory.

This enables the processing of shared properties and restrictions for the given input file.

--dry (optional)

Validates the JSON file, and checks the presence of a map service having the same name of the given JSON file.

No changes of the permission state will be done.

--metadata-validation <level> (optional)

Specifies whether and how ArcGIS Server metadata is used to perform an extended validation of policies JSON files. Among other things, the validation checks whether referenced layers exist and whether the field names used are correct.

The following options are available for the level argument:

off: No additional policy validation is performed.
warning: A validation is performed. If warnings occur during validation, these are displayed but do not lead to the command being aborted.
error: A validation is performed. If warnings occur during validation, these are displayed and cause the command to be aborted.

Default: warning

`sync`

Use secmanctl sync to synchronize access policies defined in a working directory with policies set on services of an ArcGIS Server. If security.manager NEXT is not yet activated for a service, but a policy is defined, it will be activated afterwards.

The folder structure required by this command is defined in policies working directory.

With the --delete option given, the security.manager NEXT will be deactivated for all services which are protected but have no corresponding local file.

If it is desired to apply sync to selected folders only, the --include-folders option can be used in order to provide these folders. This option can especially be useful in combination with the --delete option.

Just like the apply command, this command also supports a --dry option. With the --dry option given, no changes will be done. Instead, the command execution is simulated and changes which would be applied without the --dry option are printed to the output of this command.

Usage

$ secmanctl sync [options]

Example

$ secmanctl sync -f ./myRootFolder -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --delete --dry -vv

Options

-f, --folder <path>: Path to a policies working directory.
-d, --server-url <server-url>: ArcGIS Server base URL, e.g. https://gis.example.com:6443/arcgis.

This URL shall allow access to the ArcGIS Server Administrator Directory (/arcgis/admin). When using Integrated Windows Authentication, the Web Adaptor URL has to be used.
-t, --token <token>: An ArcGIS admin user token, used by the tool, to authenticate at ArcGIS Server Administration Directory.

When using an unfederated ArcGIS Server with IWA, no token is needed.
--iwa: Activates the support for Integrated Windows Authentication (IWA).

The Windows account is used to authenticate against ArcGIS Server.
-s, --service [<servicefolder>/]<servicename> (optional): Reduce synchronization to a single service.

Example: 'oceans', 'water/wells'
-j, --jobs <count> (optional): Execute up to count update tasks concurrently.

This option can be used to reduce (or increase) the number of update tasks which are made to server.

Default: 8
--delete (optional): Activates the deletion of existing server-side access policies for services if there are no policies for these services in the directory specified with -f.

--include-folders <list-of-foldernames> (optional)

Only include ArcGIS Server folders given as comma-separated list.

Use / for the root folder.

Example: water,traffic

--dry (optional)

Executes the synchronization without actually updating service policies on the server.

Changes which would be done without this option are printed to the output of the command.

--reverse (optional)

This option downloads the current state of the policies from the ArcGIS Server.

If you are not (yet) using a local policies working directory, this can be handy to make a local backup.
To download particular folders, the option can be used in combination with the filtering option --include-folders.
This option does not support shared policy elements and shall not be used on an existing policies working directory!

--metadata-validation <level> (optional)

The following options are available for the level argument:

off: No additional policy validation is performed.
warning: A validation is performed. If warnings occur during validation, these are displayed but do not lead to the command being aborted.
error: A validation is performed. If warnings occur during validation, these are displayed and cause the command to be aborted.

Default: warning

`groups`

Using this command, you can request the groups currently provided by ArcGIS Enterprise portal. If you are using an unfederated ArcGIS Server, this command will request the roles defined by ArcGIS Server.

In the output, the group names, the group ID, and the group owner (only for federated ArcGIS Server) are displayed.

Usage

$ secmanctl groups [options]

Examples

$ secmanctl groups -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --by-title "\"Department A\" OR Unit*"

Example: Customize JSON output

$ secmanctl groups -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --json --json-key-pattern "g_{owner}_{title}"

{
  "g_admin_dezernat_a": "7f383170dc414da99",
  "g_admin_dezernat_b": "asabb335653nrt534",
  "g_musterman_mygroup": "x34383170dc414da"
}

Options

-d, --server-url <server-url>

ArcGIS Server base URL.

This URL shall allow access to the ArcGIS Server Administrator Directory (/arcgis/admin). When using Integrated Windows Authentication, the Web Adaptor URL has to be used.

Example: https://gis.example.com:6443/arcgis

-t, --token <token>

An ArcGIS admin user token, used by the tool, to authenticate at ArcGIS Server Administration Directory.

When using an unfederated ArcGIS Server with IWA, no token is needed.

--iwa

Activates the support for Integrated Windows Authentication (IWA).

The Windows account is used to authenticate against ArcGIS Server or ArcGIS Enterprise portal.

--by-title <search-string> (optional)

Limits the results to groups whose names match the search string.

If you employ a federated ArcGIS Server, fuzzy matching as provided by portal is used. If you employ an unfederated ArcGIS Server, this command will return all roles containing the specified search string in a case-insensitive manner.

ArcGIS Enterprise portal fuzzy matching

The following characters have to be escaped: + - && || ! ( ) { } [ ] ^ " ~ * ? : /, for example --by-title "Group with $Parentheses$". General hints about the search and supported search syntax can be found in the official search reference .

--limit <amount> (optional)

Limits the amount of printed groups to the given value.

Default: -1

--json (optional)

Generates JSON formatted output.

The output is optimized for usage inside a properties.json file.

--json-key-pattern <pattern> (optional)

A pattern for customization of the group keys used in the json output format.

The expressions {title}, {owner} and {id} can be used to construct a key.

Default: {title}

`help`

The help command prints help for a given command.

Usage

$ secmanctl help [command]

Example

$ secmanctl help sync

Policies working directory

Some of the commands require a special policies working directory. The working directory is designed to mirror the structure of services and folders on an ArcGIS Server. The name of the working directory is arbitrary. It must contain a subfolder services where the policy files are stored.

It is recommended to use the hostname of the ArcGIS Server as name of the working directory.

The following example shows the expected structure of the policies working directory for an ArcGIS Server.

arcgis-public/
├── services/                   // mandatory folder
│   ├── oil/                    // folder, mapping to folder 'oil' on an ArcGIS Server
│   │   ├── pipelines.json      // policies for service "oil/pipelines"
│   │   ├── pipelines.conf.json // optional, SOI configuration for service "oil/pipelines"
│   │   └── rigs.json           // policies for service "oil/rigs"
│   ├── water/                  // folder, mapping to folder 'water' on an ArcGIS Server
│   │   ├── bassins.json        // policies for service "water/bassins"
│   │   └── wells.json          // policies for service "water/wells"
│   └── aerial_photography.json // policies for service "aerial_photography"
└── extensions.json             // optional, contains shared extension definitions
└── properties.json             // optional, contains shared property definitions
└── restrictions.json           // optional, contains shared restriction definitions

Service SOI configuration

The SOI configuration of a protected service can be defined in a <servicename>.conf.json file. It is only necessary to create such a configuration file, if non-default values shall be defined, see Configuration options below. If no configuration file is present for a protected service, all defaults apply automatically.

Example of a <servicename>.conf.json file

{
    "soi.supportReplicas": true
}

Configuration options

soi.supportReplicas: Enables replica-related operations.

If set to false, access to replica-related operations is always blocked. If set to true, security.manager NEXT allows replica-related operations on protected feature services.

Default: false

Shared policy elements

Particular parts of a policy can be defined globally.

Properties

At the root of the policies working directory, shared properties can be defined in a properties.json file. They can be used as follows:

Properties defined in that file can be referenced from all policy files in the working directory (and subfolders) by using a dollar expression (for example ${role}).
Restrictions defined in a shared restrictions.json file are allowed to reference properties from the shared properties.json.
Extensions defined in a shared extensions.json file are allowed to reference properties from the shared properties.json.

Example of a properties.json file

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.7.0/schema/policies.schema.json",
    "properties": {
        "group1": "84ac890b7627461e8b0dd0376bb8a0c2",
        "group2": "dffdab582c644df894bc1aed08609783"
    }
}

Restrictions

At the root of the the policies working directory, shared restrictions can be defined in a restrictions.json file. Restrictions defined in that file can be referenced from all policy files in the working directory (and subfolders) by name.

Example of a restrictions.json file

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.7.0/schema/policies.schema.json",
    "restrictions": {
        "restriction_only_Germany": {
            "type": "feature",
            "query": "country = 'Germany'"
        },
        "restriction_only_Ireland": {
            "type": "feature",
            "query": "country = 'Ireland'"
        }
    }
}

The file complies with the general policy format but should only contain the "restrictions" element.

Example of a referencing policy file

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.7.0/schema/policies.schema.json",
    "policies": [
        {
            "layers": [ "1", "2" ],
            "roles": [  "${group1}" ],
            "restrictions": [
                "restriction_only_Ireland"
            ]
        }
    ]
}

Extensions

You can define extensions configurations globally in an extensions.json file at the root of the policies working directory. Global extensions configurations are applied to all policy files. An extension configuration entry directly defined in a policy file overrides the according configuration properties of the globally defined extension.

Example of an extensions.json file

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.7.0/schema/policies.schema.json",
    "extensions": {
            "userInfoService": {
                "enabled": true,
                "url": "https://localhost:3333",
                "insecure": false,
                "headers": {
                    "Authorization": "Bearer 123"
                }
            }
        }
}

secmanctl

Usage

Global options

Commands

login

Usage

Example: Non-interactive login

Example: Interactive login

Example: Password from stdin

Options

apply

Usage

Example

Options

sync

Usage

Example

Options

groups

Usage

Examples

Example: Customize JSON output

Options

help

Usage

Example

Policies working directory

Service SOI configuration

Configuration options

Shared policy elements

Properties

Restrictions

Extensions

`login`

Example: Password from `stdin`

`apply`

`sync`

`groups`

`help`