secmanctl

This page contains the following sections:

Usage
Global options
Commands
- login
- apply
- sync
- groups
- help
Policies working directory
Shared policy elements
- Properties
- Restrictions

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 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.

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 like https://gis.example.com:6443/arcgis. 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.
-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.
-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. This value defaults to 60 minutes. The maximum value can be restricted by server (or portal) settings.
--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 the 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, like policies/policy.json. Use ‘-’ to read from stdin.
-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).
-s, --service [<servicefolder>/]<servicename>: Folder (optional) and name of the ArcGIS Server service the policy file will be applied to. Examples: water/wells, SampleWorldCities.
-t, --token <token>: An ArcGIS admin user token, used by the tool, to authenticate at ArcGIS Server Administration Directory.
-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.

`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 option --delete services which are protected but have no corresponding local file security.manager NEXT will be deactivated.

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 commmand.

If you like to fetch the current state of the policies from the ArcGIS Server, the --reverse option can be used to reverse the direction of the synchronization.

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).
-t, --token <token>: An ArcGIS admin user token, used by the tool, to authenticate at ArcGIS Server Administration Directory.
-s, --service [<servicefolder>/]<servicename> (optional): Reduce synchronization to a single service, like 'oceans' or 'water/wells'.
-j, --jobs <count> (optional): Execute up to 'count' update tasks concurrently (default: 8). This option can be used to reduce (or increase) the number of update tasks which are made to server.
--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, like 'water,traffic', use '/' for the root folder.
--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 reverses the direction of the synchronization process. Changes are not made to given ArcGIS Server but instead to the local policies working directory. This can be handy for fetching the current state of the policies from the ArcGIS Server and store them locally. If this option used in combination with the filtering option --include-folders, files which are not part of the given folders will be kept untouched.

`groups`

Using this command, you can request the groups currently provided by ArcGIS Enterprise. In the output, the group names, the group ID, and the group owner 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, e.g. https://gis.example.com:6443/arcgis. This URL shall allow access to the ArcGIS Server Administrator Directory (/arcgis/admin).
-t, --token <token>: An ArcGIS admin user token, used by the tool, to authenticate at ArcGIS Server Administration Directory.
--by-title <search-string> (optional): Limits the results to groups whose names match the search string. This is a fuzzy match performed by ArcGIS Portal.

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 .
--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. The default pattern is {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 can be 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"
│   │   └── 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"
└── properties.json             // optional, contains shared property definitions
└── restrictions.json           // optional, contains shared restriction definitions

Shared policy elements

Properties

In the working directory, shared properties can be defined in a properties.json file. 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.

Example of a properties.json file

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

Restrictions

In the working direcrtory, 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.0.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.0.0/schema/policies.schema.json",

    "policies": [
        {
            "layers": [ "1", "2" ],
            "roles": [  "${group1}" ],
            "restrictions": [
                "restriction_only_Ireland"
            ]
        }
    ]
}

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

Shared policy elements

Properties

Restrictions

`login`

Example: Password from `stdin`

`apply`

`sync`

`groups`

`help`