Agent Authentication

Once the Agents are installed, you cannot start working with them immediately. First you must authenticate them. There are three Authentication Methods, namely NO, LOCAL and LOCAL_REMOTE. Depending on the method you are applying, the steps to authenticate the Agents are slightly different. They are described in this topic. Agent Authentication takes place in client 0.

This topic provides information on the following:

• Authenticating the Agents
• Withdrawing the Authentication of an Agent
• Renewing the Transfer Key

Authenticating the Agents

During the installation of the Automation Engine you have:

1. Specified the Authentication Method to be applied in your system to make sure that the Automation Engine communicates with the right Agents.
2. Generated the Authentication key.
3. Installed the Agents.

Now you must authenticate them. How you do it depends on the selected Authentication Method:

• To Authenticate an Agent with "NO" Authentication Method
• To Authenticate an Agent with "LOCAL" (Server) Authentication Method 
• To Authenticate an Agent with "LOCAL_REMOTE" (Server Agent) Authentication Method

To Authenticate an Agent with "NO" Authentication Method

No manual authentication is necessary; the Authentication Key is derived automatically from the system name, the Transfer Key is automatically generated on first start of the Agent:

1. Start the Agent.

   The following happens automatically in the background:

   • An Agent object is automatically created in system client 0000. It derives the Authentication Key from the Automation Engine system name.
   • The Transfer Key is automatically generated by the Agent and the Automation Engine. The Agent stores it in its KeyStore file.
     
2. Log on to system client 0000 and switch to the Administration Perspective.
3. Assign the required client authorizations in the Agent object if you do not use automatic Agent Client Assignment.

With this method, an Agent can only log on to the Automation Engine system with the Transfer Key specifically generated for it.

Of course, you can change the Authentication Method later on.

To Authenticate an Agent with "LOCAL" (Server) Authentication Method 

1. Log on to system client 0000 and switch to the Administration Perspective.
2. Expand the Agents & Groups menu in the Administration pane and select Agents .

3. Click Export Authentication Key on the toolbar.

   A file containing the Authentication Key is downloaded.

4. Save the file containing the Authentication Key in a secure folder on the computer where the Agent runs. 

5. In the Agent INI file enter the path and the name of the Authentication Key file. You do so in the [AUTHORIZATION] section using the InitialPackage= parameter.

   In KeyStore=, enter the path and name of the Agent's KeyStore file. The agent uses the KeyStore file to store all keys used for authentication.

   Make sure that the KeyStore file is located in a secure folder accessible to the Agent.

6. Start the Agent.
7. The Agent loads the Authentication Key from the downloaded file provided by the InitialPackage= parameter and stores it in the KeyStore file. Then it deletes the original file.
8. An Agent object is automatically created in system client 0000, which must be authenticated.
9. Assign the required client authorizations in the Agent object if you do not use automatic Agent Client Assignment.
10. To authenticate the Agent:
    1. Switch to the Administration Perspective if you are not already there.

    2. Open the list of Agents and select the one you want to authenticate. Upon accessing the Agents list, the filter pane is open by default. This allows you to immediately perform a search using the Agent Name field, thus simplifying the work with the list.

    3. Right-click and select Authenticate Agent.

The Agent generates the Transfer Key using the Diffie Hellman approach and stores it in the KeyStore file. Now it is authenticated in the Automation Engine system. Authenticated Agents display a tick in the Authenticated column in the Agents list:

To Authenticate an Agent with "LOCAL_REMOTE" (Server Agent) Authentication Method

1. Log on to system client 0000 and switch to the Administration Perspective to create an Agent object.

   Its name must be the same as the one defined in the Agent INI file provided by the name= parameter (Section [GLOBAL]) .

2. Assign the required client authorizations in the Agent object if you do not use automatic Agent Client Assignment.

3. In the Agents list, right-click the Agent object you have just created and select Download Authentication Package.

   You need W (Write) permissions for the Agent object to be able to export the Authentication Package.

4. Save the authentication package in a secure folder on the computer where the Agent runs.  

5. In the Agent INI file:

   • In InitialPackage= ([AUTHORIZATION] section) enter the path and name of the Authentication Package.
   • In KeyStore= enter the path and name of the agent's KeyStore file in which the Agent will store the information retrieved from the Authentication Package.

   Make sure that both files are stored in protected directories.

6. Start the Agent.

The Agent reads the Authentication Package file and stores the information in the KeyStore file. Then it deletes the Authentication Package file. The Agent is now authenticated in the Automation Engine system.

Withdrawing the Authentication of an Agent

If you are applying the LOCAL or the LOCAL_REMOTE Authentication Methods and you want to revoke the authentication of an agent, for example because you think that it is not safe anymore, or because you are upgrading it, you have the option to Withdraw Authentication. This deletes the Authentication Key from the database.

To Withdraw the Authentication of an Agent

1. Log on to system client 0000 and switch to the Administration Perspective.
2. Expand the Agents & Groups menu in the Administration pane and select Agents. Upon accessing the Agents list, the filter pane is open by default. This allows you to immediately perform a search using the Agent Name field, thus simplifying the work with the list.

3. Right-click the Agent and select Withdraw Authentication.

The Agent is disconnected and no longer authenticated.

Renewing the Transfer Key

If you are applying the NO Authentication Method and you need to authenticate the Agent again, for example after an upgrade you want the Agent to connect to the Automation Engine system again, you have the option to Renew the Transfer Key.

The Transfer Key is the key that is shared by two communication partners within an Automation Engine system. It is generated either before or during the first connection between the Automation Engine and an Agent. It is valid for just one connection and it is used to authenticate the communication partners and to generate the session key.

To Renew the Transfer Key

1. Log on to system client 0000 and switch to the Administration Perspective.
2. Expand the Agents & Groups menu in the Administration pane and select Agents. Upon accessing the Agents list, the filter pane is open by default. This allows you to immediately perform a search using the Agent Name field, thus simplifying the work with the list.

3. Right-click the Agent and select Renew Transfer Key.