API Server Workers are assigned to keys. Keys define access to a worker, and allow IP restrictions and other security settings to be set up.
API Server Security is managed in the System Configuration section of iCM Management. Access to it is granted to users via their System Configuration Privileges.
API keys have two types - "Protected" and "Unprotected". Protected keys are pre-defined, standard keys, present in every iCM installation. They are shown with a padlock symbol and can only be edited by users with the relevant iCM Security Privilege. You should only edit protected keys with advice from us at GOSS, they are system keys that iCM and the API Server use.
Keys and Ghost Keys
You'll notice that some keys in the explorer are white, others yellow. Yellow keys are genuine keys, that is, the key needs to be supplied to invoke the workers bound to it.
White keys are "ghost keys" - they are keyless keys. Their "key" is 00000000-0000-0000-0000-000000000000, making them open.
Why do keyless keys exist?
These keys allow keyless access, but access may be restricted by IP address. For example, the INTERNAL key is "keyless" but has an IP rule that restricts access to its workers to calls from within the API Server itself. Similarly the SYSTEMOPEN key is "keyless", but has IP rules that mean workers bound to it can only be accessed from the iCM Servers.
Note that keyless keys only restrict access by IP address. When you assign workers to a keyless key any additional authentication and method filters are not checked, default credentials are not supplied.
For more information about calling workers, their security, and how to use keys see URLs, Keys and Authentication.
Creating a New API Key
To create an API key, right click the API Server Security icon in the action panel and choose "Add a new API key".
You need to define the following:
| Property | Description |
|---|---|
| Name | Can be anything, but must be unique. Use a meaningful name that makes sense for later use |
| Key | A unique key, automatically generated by iCM. You'll need to supply this when invoking workers bound to this key |
| Enabled | Uncheck this box to disable the key |
| Comments | A free text field, so you can supply information about this key to users |
| IP rules | The IP addresses from which this key can be used, or IP addresses that should be blocked. When generating a new key, iCM will automatically add the IPs for local and network addresses to its "Allow" list. At least one IP rule must be specified. When evaluating rules, the first that matches decides whether the request is accepted or rejected |
Assigning an API Worker to a Key
Once you've created a key you'll want to assign workers to it. Right-click your API key and choose "Add a new API worker".
This section of iCM lets you pick the worker you'd like to add to this key and set up any additional security that must be met before the worker can be used. You can also embed default "supplied credentials" into your worker.
Worker Properties
| Property | Description |
|---|---|
| Name | A drop-down list of all available workers. Not every worker will be listed as they may already be assigned to other keys |
| Authentication type | The option you pick here will enable one or more of the options below |
| Enable user lockout | If checked, the user supplied in the request to the worker will be locked out if the password is incorrect five times in a row. This setting has no effect if "None" is chosen for the authentication type |
Authentication Types
As well as the IP restrictions placed upon an API Server key, you can also set up authentication requirements that must be met.
Requests to the API server, whether made using the apiclient library,
There are five types.
| Type | Description |
|---|---|
| None | No user is needed. Requests can be made to this worker without supplying any credentials |
| iCM privileges | The user supplied with the request must have at least one of the selected privileges |
| iCM user group membership | The user supplied with the request must be a member of one of the selected groups |
| iCM user group membership and privileges | The user supplied with the request must be a member of one of the selected groups and have at least one of the selected privileges |
| Website users | The user supplied with the request must be a member of one of the selected groups |
Default Worker Credentials
This section allows you to supply default credentials to use with your API key. Default credentials do not provide security to keys. Rather they are credentials inserted into the request when a key is used.
For example, iCM_obj_articleUpdate requires the details of an iCM user, in whose name the update will be made. These details could be provided using the CSUserName and CSPassword properties when you use the apiclient library, but that would mean having a password visible in plain text in your code.
Instead, add default credentials to your key, which will be used as if they had been supplied with the request when none are supplied (if you do supply credentials, they will be used in preference to the default)..
Obviously, if you supply default credentials, these need to meet any requirements set by any additional authentication.
Method Filters
Method filters limit the HTTP verbs that can be passed to the worker and the methods that can be called. Each filter you add is tested in turn when this worker is invoked using this key (keep in mind that a worker may also be bound to other keys which may have different filters, or none). Requests that do not match a filter return a 401 response. As most workers only accept JSON-RPC requests the HTTP verb restrictions will only be relevant in a few cases.
Filters are particularly useful when working with end points deployed to the SECURELIBRARY worker. This worker can only be accessed browser-side with an API key and the end points deployed to it are its methods.
Regex
Regular expressions are used to define the filters. Common patterns include:
| Filter | Description |
|---|---|
| ^example\.test\..*$ | Any end point in the Note how the first and second "." characters are escaped (so they represent actual stops rather than a wildcard) and the third is used with an asterisk so that any number of any character can follow (ie all end points in this namespace can be invoked) |
| ^example\.test\.postcodeSearch$ | Only the specific end point To allow any version to be called, the filter would be |
| ^CSArticle_get|CSMedia_get$ | Either |
| ^.*$ | Anything (you could use this to allow any method and only apply HTTP verb restrictions) |
Pre-Configured Keys and Workers
Great care should be taken when assigning worker services to keys, and when creating new keys. Particular attention must be paid to those workers assigned to the open key. While public access to the worker services is limited by those exposed by a proxy, needless assignment of workers to the open key should be avoided. The standard key and worker relationships are as follows.
| Key | Workers |
|---|---|
| INTERNAL | formutils, icmapi, notification, securelibrary |
| LOCALOPEN | auth, dataintegration, email, filestore, gatekeeper, history, imageutils, postcode, serverlibrary, sitesessionstore, sms, tracer, workflow |
| MANAGEMENTCONSOLE | webajax |
| MANAGER | manager |
| OPEN | ajaxlibrary, formsservice, OAuth |
| SYSTEMOPEN | configure |
Using Keys
To find out more about using keys and calling the API Server and its workers, see URLs, Keys and Authentication.
Importing and Exporting Keys
To export a key, right-click on it and choose "Export this key". The export includes the name of the key, the IP rules, and all workers assigned to the key. For each worker, the export includes the authentication type (required iCM/site user membership or privileges), username (not password) of the default credentials, and any method filters.
Note that the key string itself is not exported.
To import a key, right-click on the root API Server Security node and choose "Import an API key".
If iCM finds any conflicts you will have the option to "Overwrite", "Ignore" or "Rename" the key you are importing.
On import a new key string is generated if the key (identified by name) does not already exist. If the key does exist, the IP rules of the existing key are overwritten by the import.
For each worker in the import, the authentication types are set up, with any groups/privileges not present on the target iCM ignored. The default credentials username is set, even if the user doesn't exist in the target iCM. Method filters are overwritten.
Share this page
