Security for agents on servers and the Web

About this task

For agents created and run in Notes® databases stored on servers or run from the Web, you can set up several levels of security controls to prevent unauthorized operations.

Who can create agents?

About this task

To control who can create agents that run on servers, use database ACLs.

Note: Web users cannot create agents.

To create

Access needed

Private agents

Reader access or higher and must have "Create private agents" enabled in the ACL

Private agents using LotusScript® and Java

Reader access or higher and must have "Create private agents" and "Create LotusScript/Java agents" enabled in the ACL

Shared agents using simple actions and formulas

Designer access or higher

Shared agents using LotusScript® or Java agents

Designer access or higher and must have "Create LotusScript/Java agents" enabled in the ACL

Who can run agents?

Procedure

To control who can run agents on servers, use the Server document in the Domino® Directory and database ACLs. See the topic "Controlling agents that run on a server" in the Domino® Administrator Help for more information.

Private agents

About this task

To control who can run private agents, open the Server document in the Address Book and click the Security tab. In the Programmability Restrictions section:

  • If everyone who can access the server can run private agents, leave "Run private agents" blank.
  • If only specific users can run private agents, specify their names in "Run private agents."

Web users cannot run private agents.

Shared agents

About this task

To control who can run shared agents, use the database ACL. Users with Reader access or higher can run shared agents.

  • If users are allowed to run shared agents, assign them Reader access or higher.
  • If users are not allowed to run shared agents, do not list them in the ACL or assign them Depositor access.

LotusScript/Java agents

About this task

LotusScript® and Java include operations that have full access to the server's system and can manipulate system time, file I/O, and operating system commands. Users or groups with unrestricted access can run an agent that includes any of these operations in the LotusScript® and Java components. Users or groups with restricted access can include most operations. The only restricted commands are those that allow access to the server's system.

CAUTION: Unrestricted Java and LotusScript® agents can potentially violate security. Only a limited number of trusted users should have unrestricted rights.

Where can agents run?

About this task

To control whether agents are allowed to run on servers, use the Server document in the Address Book. Click the Security tab. In the Server Access section:

  • If everyone running an agent that accesses the server is allowed to access the server, leave "Access server" blank.
  • If you don't want users accessing the server either directly or through agents, specify the user names in "Access server." Then, if a user who is not specified attempts to run an agent that accesses the server, the agent is not run. You can also specify user names in "Not access server."
    Note: These restrictions apply to agents running from other servers or from a client. Agents that are already scheduled to run on the server will not be affected by the Server Access section.

What operations can agents run?

About this task

To control which documents agents can process, Domino® checks the ACL of the database where the documents are stored, as follows:

  • For agents that use simple actions, LotusScript®, and Java, Domino® checks the user's ACL.
  • For agents that use formulas, Domino® checks the replica ID of the database in which the agents were created. Therefore, to ensure that agents using formulas can access documents in other databases, you must list the database replica ID in each database the agent will access.

To control whether agents are allowed to create databases, use the Server document in the Address Book. Click the Security tab. In the Server Access Section:

  • If everyone is allowed to create databases, leave "Create databases & templates" blank. Then, anyone running an agent that creates new databases can do so on the server.
  • If you don't want all users creating databases, specify the user names of people allowed to create databases in "Create databases & templates." Then, if a user who is not specified runs an agent that creates a database, an error is reported and the database is not created.

When are restrictions checked?

About this task

Domino® checks the security restrictions differently depending on whether the agent is running:

  • Locally or on the server
  • In the foreground or background
  • If the agent is started from the Web or the Notes® client

Locally on Notes®

About this task

An agent runs locally when:

  • It runs within a Notes® client database.
  • You choose "Local" from the "Run on" list for a scheduled agent.
  • A user starts the agent from the Actions menu in the Notes® client, from the Agent - Run menu in Domino® Designer, from the "When documents Have Been Pasted" trigger, or from calling the agent by agent.run.

When an agent runs locally, Notes® does not check security restrictions, unless you have set the Enforce ACL option. (To set the Enforce ACL option, choose File - Database - Access Control and then click the Advanced icon.)

On the server

About this task

An agent runs on the server when it is running in a database stored on a server and it is started by one of the following:

  • Before new mail arrives
  • After new mail arrives
  • If documents have been created or updated
  • On schedule more than once a day
  • On schedule daily
  • On schedule weekly
  • On schedule monthly
  • Called by an agent via agent.runonserver (the agent being called must reside on the server)

If the agent is running on a server, Domino® checks all security restrictions.

Foreground or background

About this task

An agent runs in the foreground when a user starts it from the Notes® Actions menu, selects it from the Designer Agents list, or clicks an Action button. When agents run in the foreground, security restrictions are not checked.

An agent runs in the background when it is scheduled or it is triggered by an event (for example, when documents are modified) or when it is called by agent.runonserver. When agents run in the background, Domino® checks security restrictions.

From the Notes® client or the Web

About this task

Agents run in the Notes® client or on the Web based on the effective user. The effective user is the user under whose authority the agent runs. The effective user depends on the environment in which the agent runs.

Agent type

Effective user

Notes® client agent

Current® user ID

Web agent

One of the following:

  • Current® Web user
  • Agent signer (agent owner)
  • On behalf of (set in the Security tab of the Agent Properties box).

Scheduled agent

Either:

  • Agent signer (agent owner)
  • On behalf of (set in the Security tab of the Agent Properties box).

When a Web user runs an agent, the agent also runs using the rights of the effective user and Domino® checks the effective user's rights to access the database. However, you can set up the agent so that Domino® checks the invoker's rights to access the database instead of the effective user's rights. Checking the invoker's rights can provide more security.

To specify that Domino® verify the invoker's access to the database, follow these steps:

Procedure

  1. Double-click an agent name in the agent list.
  2. Click the Security tab.
  3. Check "Run as Web user."

Results

When "Run as Web user" is checked, Domino® prompts Web users for their name and password when they attempt to run the agent. Domino® uses the login information to check for the invoker's rights in the database ACL.

Security controls for agents that are called by agents

About this task

When agents call other agents, Domino® checks the security restrictions for each agent. However, when the agent signers are different, Domino® checks security as follows:

  • If the first agent uses simple actions or formulas:
  • If the first agent uses LotusScript® or Java: