Java Policy Agents 5.9.1

Reference

agentadmin Command

The agentadmin command manages Java Agent installation. It requires a Java runtime environment.

The command supports the following options:

--install

Installs a new agent instance.

Usage: agentadmin --install [--useResponse | --saveResponse file-name] [--acceptLicence]

When the command is used without options, the installation process prompts for the following information:

  • Confirmation that you have read and accepted the software license agreement.

  • Information about the container installation.

  • The URL to the AM instance. The Java Agent confirms that it can log in to AM by using the profile name and password provided during installation. If unsuccessful, the installation stops with an error.

  • The URL to the Java Agent instance. The Java Agent confirms that it can access the host and port of the URL. If the port is busy, it prompts the user to stop the container.

  • The Java Agent profile name in AM.

  • The AM realm containing the Java Agent profile.

  • The path to the file containing the Java Agent password.

    --useResponse

    Run in silent mode by specifying all the responses in the file-name file. When this option is used, agentadmin runs in non-interactive mode.

    --saveResponse

    Save all the supplied responses in a response file specified by file-name.

    --acceptLicense

    Confirms automatically that you have read and accept the software license agreement, without prompting you to agree. To view the license agreement, open <server-root>/legal-notices/license.txt.file-name .

--forceInstall

Installs a new Java Agent instance, without checking the AM URL or Java Agent URL.

Usage: agentadmin --forceInstall [--useResponse | --saveResponse file-name] [--acceptLicence]

When the command is used without options, the installation process prompts for the following information:

  • Confirmation that you have read and accepted the software license agreement.

  • Information about the container installation.

  • The URL to the AM instance. The Java Agent does not confirm that it can log in to AM. Take care to provide a valid URL.

  • The URL to the Java Agent instance. The Java Agent does not confirm that it can access the URL. Take care to provide a valid URL.

  • The Java Agent profile name in AM.

  • The AM realm containing the Java Agent profile.

  • The path to the file containing the Java Agent password.

    --useResponse

    Run in silent mode by specifying all the responses in the file-name file. When this option is used, agentadmin runs in non-interactive mode.

    --saveResponse

    Save all the supplied responses in a response file specified by file-name.

    --acceptLicense

    Confirms automatically that you have read and accept the software license agreement, without prompting you to agree. To view the license agreement, open <server-root>/legal-notices/license.txt.file-name .

--custom-install

Installs a new agent instance, specifying advanced configuration options.

Usage: agentadmin --custom-install [--useResponse | --saveResponse file-name] [--acceptLicence]

--useResponse

Run in silent mode by specifying all the responses in the file-name file. When this option is used, agentadmin runs in non-interactive mode.

--saveResponse

Save all the supplied responses in a response file specified by file-name.

--acceptLicense

Confirms automatically that you have read and accept the software license agreement, without prompting you to agree. To view the license agreement, open <server-root>/legal-notices/license.txt.file-name .

--uninstall

Uninstalls an existing agent instance.

Usage: agentadmin --uninstall [--useResponse | --saveResponse file-name]

--useResponse

Run in silent mode by specifying all the responses in the file-name file. When this option is used, agentadmin runs in non-interactive mode.

--saveResponse

Save all the supplied responses in a response file specified by file-name.

--version

Displays the version information.

--uninstallAll

Uninstalls all the agent instances.

--listAgents

Displays details of all the configured agents.

--agentInfo

Displays information about the agent corresponding to the specified agent-id.

Usage: agentadmin --agentInfo agent-id

Example: agentadmin --agentInfo agent_001

--encrypt

Encrypts a given string.

Usage: agentadmin --encrypt agent-instance password-file

agent-instance

Agent instance identifier. The encryption functionality requires the use of agent instance specific encryption key present in its configuration file.

password-file

File containing the password to encrypt.

--getEncryptKey

Generates an agent encryption key.

Configure Apache HTTP Server As a Reverse Proxy Example

This section provides an example of how to configure Apache as a reverse proxy between AM and the agent. You can use any reverse proxy that supports the WebSocket protocol.

Refer to the Apache documentation to configure Apache for load balancing and any other requirement for your environment.

Simplified image of a reverse proxy configuration between AM and the agent.
Figure 1. Reverse Proxy Configured Between the Agent and AM

Note that the communication protocol changes from HTTPS to HTTP.

Configure Apache as a Reverse Proxy Example
  1. In your deployed reverse proxy instance, locate the httpd.conf file.

  2. Add the following modules required for a proxy configuration:

    # Modules required for proxy
    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_http_module modules/mod_proxy_http.so
    LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

    The mod_proxy_wstunnel.so module is required to support the WebSocket protocol used for notification between AM and the agents.

  3. Add the proxy configuration inside the VirtualHost context, and set the following directives:

    <VirtualHost 192.168.1.1>
    ...
    # Proxy Config
    RequestHeader set X-Forwarded-Proto "https" (1)
    ProxyPass "/openam/notifications" "ws://openam.example.com:8080/openam/notifications"
    Upgrade=websocket (2)
    ProxyPass "/openam" "http://openam.example.com:8080/openam" (3)
    ProxyPassReverseCookieDomain "openam.internal.example.com" "proxy.example.com" (4)
    ProxyPassReverse "/openam" "http://openam.example.com:8080/openam" (5)
    ...
    </VirtualHost>
    1 RequestHeader: If the proxy is configured for https, set to https. Otherwise, set to http. A later step configures AM to recognize the forwarded header and use it in the goto parameter, to redirect back to the Java Agent after authentication.
    2 ProxyPass: Allow WebSocket traffic between AM and the Java Agent. If HTTPS is configured between the proxy and AM, use wss instead of ws.
    3 ProxyPass: Allow HTTP traffic between AM and the agent.
    4 ProxyPassReverseCookieDomain: Rewrite the domain string of Set-Cookie headers in this format: internal domain (AM’s domain) public domain (proxy’s domain).
    5 ProxyPassReverse: Set to the same value configured for the ProxyPass directive.
  4. Restart the reverse proxy instance.

  5. Configure AM to recover the forwarded header configured in the reverse proxy. Also, review other configurations that may be required in an environment that uses reverse proxies. For more information, see Communication Between AM and Agents

Implement a Custom Task Handler

This section describes how to add a custom task handler to the list of handlers, and provides example handlers. At startup, Java Agent tries to instantiate the specified service resolver class. If unsuccessful, it instantiates the original service resolver.

  1. Place com.sun.identity.agents.arch.ServiceResolver on the classpath.

  2. Add com.sun.identity.agents.arch.ServiceResolver to the bootstrap property Service Resolver Class Name.

Use the following functions to return a list of class names to customize the task handler:

Function When to execute the class What the class must implement

List<String> getPreInboundTaskHandlers()

Before all other inbound task handlers

IAmFilterTaskHandler

List<String> getPostInboundTaskHandlers()

After all other inbound task handlers

IAmFilterTaskHandler

List<String> getPreSelfRedirectHandlers()

Before all other self-redirect task handlers

IAmFilterTaskHandler

List<String> getPostSelfRedirectHandlers()

After all other self-redirect task handlers

IAmFilterTaskHandler

List<String> getPreFilterResultHandlers()

Before all other result handlers

IAmFilterResultHandler

List<String> getPostFilterResultHandlers()

After all other result handlers

IAmFilterResultHandler.

If the named handler classes are not on the classpath, or do not implement the required interface, then:

  • Handler instantiation fails.

  • A message is logged at ERROR level.

  • The agent abandons processing and returns an HTTP 500, effectively denying all requests.

When a handler list is built, make sure that any isActive function implemented by your custom handler returns true, if appropriate. Any handler returning false is evicted.

For each InboundTaskHandler and SelfRedirectHandler, the process function is invoked until a non-null value, such as continue or block, is returned. The non-null value becomes the result for that resource access. Returning a null value indicates to carry on to the other handlers.

For FilterResultHandlers, returning a null value causes an error.

Example Custom Filter Result Task Handler

/*
 * Copyright 2019-2021 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */
package com.sun.identity.agents.custom;

import static org.forgerock.agents.debug.AgentDebug.logTrace;

import javax.servlet.http.HttpServletRequest;

import org.forgerock.agents.util.Utils;

import com.sun.identity.agents.arch.AgentConfiguration;
import com.sun.identity.agents.arch.Manager;
import com.sun.identity.agents.filter.AmFilterMode;
import com.sun.identity.agents.filter.AmFilterRequestContext;
import com.sun.identity.agents.filter.AmFilterResult;
import com.sun.identity.agents.filter.AmFilterResultHandler;

/**
 * This is an example of a custom filter result task handler
 */
@SuppressWarnings("unused")
public class CustomFilterResultTaskHandler extends AmFilterResultHandler {

    public CustomFilterResultTaskHandler(Manager manager) {
        super(manager);
    }

    @Override
    public boolean isActive() {
        return true;
    }

    @Override
    public String getHandlerName() {
        return "CustomFilterResultTaskHandler";
    }

    @Override
    public AmFilterResult process(AmFilterRequestContext context, AmFilterResult result) {

        String applicationName = Utils.getApplicationName(context);
        AmFilterMode amFilterMode = AgentConfiguration.getTheFilterMode(applicationName);
        HttpServletRequest request = context.getHttpServletRequest();

        logTrace("Hello from {}, application name {}, filter mode {}, {} {}, result {}",
                getHandlerName(), applicationName, amFilterMode,
                request.getMethod(), request.getRequestURI(),
                result.toString());


        // Must return the result parameter, unless you have a really good reason not to.
        return result;
    }
}

Example Custom Self-Redirect Task Handler

/*
 * Copyright 2019-2021 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */
package com.sun.identity.agents.custom;

import static org.forgerock.agents.debug.AgentDebug.logTrace;

import javax.servlet.http.HttpServletRequest;

import org.forgerock.agents.util.Utils;

import com.sun.identity.agents.arch.AgentConfiguration;
import com.sun.identity.agents.arch.AgentException;
import com.sun.identity.agents.arch.Manager;
import com.sun.identity.agents.filter.AmFilterMode;
import com.sun.identity.agents.filter.AmFilterRequestContext;
import com.sun.identity.agents.filter.AmFilterResult;
import com.sun.identity.agents.filter.AmFilterTaskHandler;
import com.sun.identity.agents.filter.IBaseAuthnContext;

/**
 * This is an example of a custom self-redirect task handler.  It is essentially the same as the inbound task
 * handler.
 */
@SuppressWarnings("unused")
public class CustomSelfRedirectTaskHandler extends AmFilterTaskHandler {

    public CustomSelfRedirectTaskHandler(Manager manager) {
        super(manager);
    }

    @Override
    public void initialize(IBaseAuthnContext context) throws AgentException {
        super.initialize(context);
    }

    @Override
    public boolean isActive() {
        return true;
    }

    @Override
    public String getHandlerName() {
        return "Custom self redirect task handler";
    }

    @Override
    public AmFilterResult process(AmFilterRequestContext context) {

        String applicationName = Utils.getApplicationName(context);
        AmFilterMode amFilterMode = AgentConfiguration.getTheFilterMode(applicationName);
        HttpServletRequest request = context.getHttpServletRequest();

        logTrace("Hello from {}, application name {}, filter mode {}, {} {}",
                getHandlerName(), applicationName, amFilterMode,
                request.getMethod(), request.getRequestURI());

        // return null to continue to the other task handlers (until one returns a non null value)
        // return AmFilterResultStatus.STATUS_CONTINUE to grant access (continue to the next filter after the agent)
        // return AmFilterResultStatus.STATUS_REDIRECT to redirect somewhere else
        // return AmFilterResultStatus.STATUS_FORBIDDEN to deny access
        // return AmFilterResultStatus.STATUS_SERVE_DATA to serve up data to the browser
        // return AmFilterResultStatus.STATUS_SERVER_ERROR to abort the request with a 500 server error
        //
        return null;
    }
}

Example Custom Inbound Task Handler

/*
 * Copyright 2019-2021 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */
package com.sun.identity.agents.custom;

import static org.forgerock.agents.debug.AgentDebug.logTrace;

import javax.servlet.http.HttpServletRequest;

import org.forgerock.agents.util.Utils;

import com.sun.identity.agents.arch.AgentConfiguration;
import com.sun.identity.agents.arch.AgentException;
import com.sun.identity.agents.arch.Manager;
import com.sun.identity.agents.filter.AmFilterMode;
import com.sun.identity.agents.filter.AmFilterRequestContext;
import com.sun.identity.agents.filter.AmFilterResult;
import com.sun.identity.agents.filter.AmFilterTaskHandler;
import com.sun.identity.agents.filter.IBaseAuthnContext;

/**
 * This is an example of a custom inbound task handler
 */
@SuppressWarnings("unused")
public class CustomInboundTaskHandler extends AmFilterTaskHandler {

    public CustomInboundTaskHandler(Manager manager) {
        super(manager);
    }

    @Override
    public void initialize(IBaseAuthnContext context) throws AgentException {
        super.initialize(context);
    }

    @Override
    public boolean isActive() {
        return true;
    }

    @Override
    public String getHandlerName() {
        return "Custom inbound task handler";
    }

    @Override
    public AmFilterResult process(AmFilterRequestContext context) {

        String applicationName = Utils.getApplicationName(context);
        AmFilterMode amFilterMode = AgentConfiguration.getTheFilterMode(applicationName);
        HttpServletRequest request = context.getHttpServletRequest();

        logTrace("Hello from {}, application name {}, filter mode {}, {} {}",
                getHandlerName(), applicationName, amFilterMode,
                request.getMethod(), request.getRequestURI());

        // return null to continue to the other task handlers (until one returns a non null value)
        // return AmFilterResultStatus.STATUS_CONTINUE to grant access (continue to the next filter after the agent)
        // return AmFilterResultStatus.STATUS_REDIRECT to redirect somewhere else
        // return AmFilterResultStatus.STATUS_FORBIDDEN to deny access
        // return AmFilterResultStatus.STATUS_SERVE_DATA to serve up data to the browser
        // return AmFilterResultStatus.STATUS_SERVER_ERROR to abort the request with a 500 server error
        //
        return null;
    }
}

Example of How to Override the ServiceResolver Class

/*
 * Copyright 2019-2021 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */
package com.sun.identity.agents.custom;

import java.util.ArrayList;
import java.util.List;

import com.sun.identity.agents.arch.ServiceResolver;

/**
 * This is an example of how to override the ServiceResolver class to provide your own custom task handlers.  To use
 * this example class, place the following in the custom properties on the advanced tab in the Java Agents profile:
 * <p></p>
 * org.forgerock.agents.service.resolver.class.name=com.sun.identity.agents.custom.CustomServiceResolverExample
 * <p></p>
 * and restart the agent.
 */
@SuppressWarnings("unused")
public class CustomServiceResolverExample extends ServiceResolver {

    @Override
    public List<String> getPreInboundTaskHandlers() {
        List<String> result = new ArrayList<>();
        result.add(CustomInboundTaskHandler.class.getName());
        return result;
    }

    @Override
    public List<String> getPostInboundTaskHandlers() {
        return new ArrayList<>();
    }

    @Override
    public List<String> getPreSelfRedirectHandlers() {
        List<String> result = new ArrayList<>();
        result.add(CustomSelfRedirectTaskHandler.class.getName());
        return result;
    }

    @Override
    public List<String> getPostSelfRedirectHandlers() {
        return new ArrayList<>();
    }

    @Override
    public List<String> getPreFilterResultHandlers() {
        List<String> result = new ArrayList<>();
        result.add(CustomFilterResultTaskHandler.class.getName());
        return result;
    }

    @Override
    public List<String> getPostFilterResultHandlers() {
        return new ArrayList<>();
    }
}
Copyright © 2010-2022 ForgeRock, all rights reserved.