PingAM

https://docs.pingidentity.com/pingam/7.5/
Admin
PingAM is an Identity and Access Management (IAM) solution that provides authentication,...
Tokens:6,421,747
Snippets:36,494
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Amster Command Help Example (connect)

Source: https://docs.pingidentity.com/pingam/7.5/amster/install-amster

Illustrates how to get detailed help for a specific Amster command, using 'connect' as an example. It shows the command's usage, options, and provides usage examples.

```bash
am> :help connect
```

--------------------------------

### Starting and Exiting Amster

Source: https://docs.pingidentity.com/pingam/7.5/amster/install-amster

Instructions on how to start the Amster client and exit the shell.

```APIDOC
## Starting and Exiting Amster

### Description
This section covers the initial steps to start the Amster command-line client and how to gracefully exit the shell once operations are complete.

### Starting Amster

1. Extract the Amster archive.
2. Navigate to the extracted directory.
3. Run the `amster` command.

```bash
$ cd /path/to/amster
$ ./amster
```

Upon successful startup, the Amster OpenAM Shell will be displayed, including version information.

### Exiting Amster

To exit the Amster shell, use either the `:exit` or `:q` commands.

```
am> **:exit**
$
```

Or

```
am> **:q**
$
```
```

--------------------------------

### AM Silent Installation Output Example

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/silent-install

Provides an example of the output generated during a silent AM installation. It shows the progress of various stages, such as license checking, configuration store installation, OpenDJ setup, and system configuration, confirming a successful installation.

```bash
java -jar openam-configurator-tool-14.1.3.28.jar --file config.properties
Checking license acceptance…License terms accepted.
Checking configuration directory /home/openam….Success.
Installing OpenAM configuration store…Success RSA/ECB/OAEPWithSHA1AndMGF1…
Extracting OpenDJ, please wait…Complete
Running OpenDJ setupSetup command: --cli --adminConnectorPort 4444
--baseDN dc=openam,dc=forgerock,dc=org --rootUserDN uid=admin
--ldapPort 50389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
--no-prompt --doNotStart --hostname openam.example.com …
…Success
Installing OpenAM configuration store in /home/openam/… …Success.
Creating OpenAM suffixImport+task+ … …Success
Tag swapping schema files….Success.
Loading Schema opendj_config_schema.ldif…Success.

…

…Success.
Reinitializing system properties….Done
Registering service dashboardService.xml…Success.

…

Configuring system….Done
Configuring server instance….Done
Creating demo user….Done
Creating Web Service Security Agents….Done
Setting up monitoring authentication file.
Configuration complete!
```

--------------------------------

### Start Identity Repository

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/PluginTools

Starts an existing identity repository. This method should be called during plugin installation and startup. It requires an `IdRepoConfig` annotated class and may throw `PluginException` or `IllegalArgumentException`.

```java
void startIdRepo(Class<?> idRepoConfig) throws PluginException
```

--------------------------------

### Handle Plugin Startup in AbstractNodeAmPlugin

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/auth/node/api/AbstractNodeAmPlugin

Implements the onStartup method from the AmPlugin interface. This method is invoked every time AM starts, following installation or upgrade procedures.

```java
public void onStartup(org.forgerock.openam.plugins.StartupType startupType) throws PluginException

```

--------------------------------

### Start Authentication Node

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/PluginTools

Starts an existing authentication node. This method should be called during plugin installation and startup. It requires a `Node` class annotated with `org.forgerock.openam.annotations.sm.Config` and can throw `PluginException` or `IllegalArgumentException`.

```java
void startAuthNode(Class<?> nodeClass) throws PluginException
```

--------------------------------

### Start Amster Client

Source: https://docs.pingidentity.com/pingam/7.5/amster/install-amster

This snippet shows how to navigate to the Amster directory and launch the Amster client. The output indicates the client version and JDK version. Ensure JAVA_HOME is set and a supported JDK is used.

```bash
$ cd /path/to/amster
$ ./amster
```

--------------------------------

### Configure /etc/hosts for AM Installation (Linux)

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/install-custom

Example lines for the /etc/hosts file on a Linux system to simulate a Fully Qualified Domain Name (FQDN) for AM installation in test or QA environments.

```bash
127.0.0.1 localhost.localdomain localhost
::1 localhost6.localdomain6 localhost6
127.0.1.1 openam openam.example.com
```

--------------------------------

### Display Amster Help

Source: https://docs.pingidentity.com/pingam/7.5/amster/install-amster

This snippet shows how to display the list of available commands in the Amster client using the ':help' command. It also lists aliases and provides guidance on getting help for specific commands.

```bash
am> :help
```

--------------------------------

### Verify Maven and Java Versions

Source: https://docs.pingidentity.com/pingam/7.5/auth-nodes/preparing-for-nodes

This command verifies the installed versions of Apache Maven and the Java Development Kit (JDK) on your system. It's a prerequisite for building custom authentication nodes.

```bash
$ mvn --version
Maven home: /usr/local/Cellar/maven/3.6.0/libexec
Java version: 11.0.4, vendor: AdoptOpenJDK, runtime: /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.16", arch: "x86_64", family: "mac"
```

--------------------------------

### Handle Plugin Installation in AbstractNodeAmPlugin

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/auth/node/api/AbstractNodeAmPlugin

Implements the onInstall method from the AmPlugin interface. This method is called once upon the plugin's initial inclusion in the classpath and AM startup.

```java
public void onInstall() throws PluginException

```

--------------------------------

### CrestBooleanSchema Example Property (Get)

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/api/jackson/CrestBooleanSchema

Gets the 'example' JSON Schema field. This method is specified by the WithExampleSchema interface and returns the example value or null.

```java
public Boolean getExample()
// Specified by: getExample in interface WithExampleSchema<Boolean>
```

--------------------------------

### Example Authorization Policy for Session Upgrade

Source: https://docs.pingidentity.com/pingam/7.5/sessions-guide/session-upgrade

This policy grants GET and POST access to a specific resource for any authenticated user, demonstrating a basic authorization setup for session upgrade scenarios.

```text
The following policy allows GET and POST access to the `*://*:*/sample/*` resource to any authenticated user:
Figure 1. Authorization Policy Example
```

--------------------------------

### Get SSLContext for SSL Layer Installation

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/opendj/security/SslOptions

Returns the SSLContext instance that should be utilized when installing the SSL layer.

```java
public SSLContext sslContext()
Returns the `SSLContext` that should be used when installing the SSL layer.
```

--------------------------------

### Run ssoadm Setup Utility

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/install-openam-admin-tools

Executes the 'setup' utility to configure the ssoadm tool. It requires parameters for the truststore path, password, type, and optionally accepts the license agreement.

```bash
$ ./setup --truststore-path /my/ssoadm/truststore --truststore-password changeit \
--truststore-type JKS --acceptLicense
Path to config files of OpenAM server [/home/user/openam]:
Debug Directory [/path/to/openam-tools/admin/debug]:
Log Directory [/path/to/openam-tools/admin/log]:
The scripts are properly setup under directory:
/path/to/openam-tools/admin/openam
Debug directory is /path/to/openam-tools/admin/debug.
Log directory is /path/to/openam-tools/admin/log.
The version of this tools.zip is: version and date
The version of your server instance is: ForgeRock Access Management version, Build, and date
```

--------------------------------

### Amster install-openam help

Source: https://docs.pingidentity.com/pingam/7.5/amster/configure-am-with-amster

Command to display all available options for the Amster install-openam command.

```cli
:help install-openam
```

--------------------------------

### Get Example Value (Java)

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/api/jackson/WithExampleSchema

Retrieves the example value from a schema. This method is part of the WithExampleSchema interface.

```java
T getExample()
Gets `example` JSON Schema field.

Returns:
    The example value, or null if not defined.
```

--------------------------------

### Get Attribute Start Range (Java)

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/com/sun/identity/sm/AttributeSchema

Retrieves the starting value of a range for attributes defined with NUMBER_RANGE or DECIMAL_RANGE syntax. Returns the start range as a string.

```java
public String getStartRange()
Returns the start range if the attribute syntax is either `NUMBER_RANGE` or `DECIMAL_RANGE`.
```

--------------------------------

### AmPlugin onInstall Method

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/AmPlugin

Details the onInstall method, which handles the initial installation of a plugin. It is called only once when the plugin is first added to the classpath and executed before onStartup.

```java
void onInstall() throws PluginException
// Handle plugin installation. This method will only be called once, on first AM startup once the plugin is included in the classpath.
```

--------------------------------

### PingAM Bootstrap File Example (boot.json)

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/startup-openam

An example of the AM bootstrap file ('boot.json') showing the structure for defining AM server instance, keystore settings, and configuration store details. This file is crucial for overriding startup configurations.

```json
{
  "instance": "https://openam.example.com:8443/openam",
  "dsameUser": "cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org",
  "keystores": {
    "default": {
      "keyStorePasswordFile": "{amSecretsBase}/default/.storepass",
      "keyPasswordFile": "{amSecretsBase}/default/.keypass",
      "keyStoreType": "JCEKS",
      "keyStoreFile": "{amKeystoreBase}/keystore.jceks"
    }
  },
  "configStoreList": [
    {
      "baseDN": "ou=am-config",
      "dirManagerDN": "uid=am-config,ou=admins,ou=am-config",
      "ldapHost": "opendj.example.com",
      "ldapPort": 1636,
      "ldapProtocol": "ldap"
    }
  ]
}
```

--------------------------------

### CrestAnySchema Example Methods

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/api/jackson/CrestAnySchema

Methods to get and set the example JSON Schema field. The setExample method can throw an IOException.

```java
public Object getExample()
public void setExample(String example) throws IOException
```

--------------------------------

### Sample Authentication Module Implementation (Java)

Source: https://docs.pingidentity.com/pingam/7.5/authentication-guide/about-authentication-modules-and-chains

A comprehensive example of a PingAM authentication module, `SampleAuth.java`. It demonstrates the implementation of the `init` and `process` methods, including handling callbacks, managing state, and interacting with PingAM's logging and localization features. This code serves as a foundation for creating custom authentication logic.

```java
/*
 * The contents of this file are subject to the terms of the Common Development and
 * Distribution License (the License). You may not use this file except in compliance with the
 * License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
 * specific language governing permission and limitations under the License.
 *
 * When distributing Covered Software, include this CDDL Header Notice in each file and include
 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
 * Header, with the fields enclosed by brackets [] replaced by your own identifying
 * information: "Portions copyright [year] [name of copyright owner]".
 *
 * Copyright 2011-2023 ForgeRock AS. All Rights Reserved
 */

package org.forgerock.openam.examples;

import java.security.Principal;
import java.util.Map;
import java.util.ResourceBundle;
import java.util.Set;

import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.login.LoginException;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.sun.identity.authentication.spi.AMLoginModule;
import com.sun.identity.authentication.spi.AuthLoginException;
import com.sun.identity.authentication.spi.InvalidPasswordException;
import com.sun.identity.authentication.util.ISAuthConstants;
import com.sun.identity.shared.datastruct.CollectionHelper;

/**
 * SampleAuth authentication module example.
 *
 * If you create your own module based on this example, you must modify all
 * occurrences of "SampleAuth" in addition to changing the name of the class.
 *
 * Please refer to OpenAM documentation for further information.
 *
 * Feel free to look at the code for authentication modules delivered with
 * OpenAM, as they implement this same API.
 */
public class SampleAuth extends AMLoginModule {

    // Name for the debug-log
    private final static String DEBUG_NAME = "SampleAuth";
    private final static Logger debug = LoggerFactory.getLogger(SampleAuth.class);

    // Name of the resource bundle
    private final static String amAuthSampleAuth = "amAuthSampleAuth";

    // User names for authentication logic
    private final static String USERNAME = "demo";
    private final static String PASSWORD = "Ch4ng31t";

    private final static String ERROR_1_USERNAME = "test1";
    private final static String ERROR_2_USERNAME = "test2";

    // Orders defined in the callbacks file
    private final static int STATE_BEGIN = 1;
    private final static int STATE_AUTH = 2;
    private final static int STATE_ERROR = 3;

    // Errors properties
    private final static String SAMPLE_AUTH_ERROR_1 = "sampleauth-error-1";
    private final static String SAMPLE_AUTH_ERROR_2 = "sampleauth-error-2";

    private Map<String, Set<String>> options;
    private ResourceBundle bundle;
    private Map<String, String> sharedState;

    public SampleAuth() {
        super();
    }


    /**
     * This method stores service attributes and localized properties for later
     * use.
     * @param subject
     * @param sharedState
     * @param options
     */
    @Override
    public void init(Subject subject, Map sharedState, Map options) {

        debug.debug("SampleAuth::init");

        this.options = options;
        this.sharedState = sharedState;
        this.bundle = amCache.getResBundle(amAuthSampleAuth, getLoginLocale());
    }

    @Override
    public int process(Callback[] callbacks, int state) throws LoginException {

```

--------------------------------

### Set and Get Example JSON Schema Field - PingAM 7.5

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/api/jackson/CrestObjectSchema

Methods to manage the 'example' field in the JSON Schema. setExample takes a String representation of the example value and parses it, potentially throwing an IOException. getExample retrieves the example value.

```java
public Map<String,Object> getExample()
public void setExample(String example) throws IOException
```

--------------------------------

### Install AM with Default Settings

Source: https://docs.pingidentity.com/pingam/7.5/amster/configure-am-with-amster

Installs a single AM instance using the `amster` command with default values. This includes setting the server URL, admin password, and accepting the license. The embedded configuration store is utilized, and a demo user is created.

```shell
am> **install-openam \
 --serverUrl https://openam.example.com:8443/openam \
 --adminPwd forgerock \
 --acceptLicense**
```

--------------------------------

### Get Guide Syntax

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/opendj/ldap/schema/CoreSchema

Retrieves a reference to the Guide Syntax, identified by OID 1.3.6.1.4.1.1466.115.121.1.25. This method is part of the core schema.

```java
public static Syntax getGuideSyntax()
Returns a reference to the `Guide Syntax` which has the OID `1.3.6.1.4.1.1466.115.121.1.25`.

Returns:
    A reference to the `Guide Syntax`.
```

--------------------------------

### Get Guide Syntax Reference

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/opendj/ldap/schema/CoreSchema

Returns a reference to the Guide Syntax, identified by OID 1.3.6.1.4.1.1466.115.121.1.25. This is a static method of the Syntax class.

```java
static Syntax getGuideSyntax()
Returns a reference to the `Guide Syntax` which has the OID `1.3.6.1.4.1.1466.115.121.1.25`.
```

--------------------------------

### Install First PingAM Instance with Amster

Source: https://docs.pingidentity.com/pingam/7.5/amster/configure-am-with-amster

Installs the initial PingAM instance using Amster. It configures the server URL, admin password, license acceptance, cookie domain, site name, configuration directory, and details for connecting to the configuration store (like host, port, SSL, and directory manager credentials).

```Shell
amster install-openam \
 --adminPwd forgerock \
 --acceptLicense \
 --cookieDomain example.com \
 --lbSiteName TestSite01 \
 --cfgDir /tomcat/openam1 \
 --lbPrimaryUrl http://site.example.com:80/openam \
 --cfgStore dirServer \
 --cfgStoreHost opendj.example.com \
 --cfgStoreAdminPort 3444 \
 --cfgStorePort 1636 \
 --cfgStoreSsl SSL \
 --cfgStoreRootSuffix dc=examplecfg1,dc=com \
 --cfgStoreDirMgr uid=admin \
 --cfgStoreDirMgrPwd mySecretPassword
```

--------------------------------

### get Method Implementation Example (Conceptual)

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/sts/tokengeneration/saml2/statements/AuthzDecisionStatementsProvider

Illustrates a basic implementation of the 'get' method for AuthzDecisionStatementsProvider. It should return a non-null list, even if empty.

```java
List<AuthzDecisionStatement> get(SSOToken ssoToken, SAML2Config config) {
    // Implementation to create and return AuthzDecisionStatement objects
    // Example: return Collections.emptyList(); if no statements are generated
    return Collections.emptyList();
}
```

--------------------------------

### Start Identity Repository

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/PluginTools

Starts an existing identity repository.

```Java
void startIdRepo(Class<?> idRepoConfig)
```

--------------------------------

### Get Attribute Example Values

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/com/sun/identity/sm/ServiceSchema

Retrieves a map of all attributes and their example values as defined in the schema. Returns a Map<String, Set<String>>.

```Java
public Map<String,Set<String>> getAttributeExamples()

```

--------------------------------

### Get Enhanced Guide Syntax

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/opendj/ldap/schema/CoreSchema

Retrieves a reference to the Enhanced Guide Syntax, identified by OID 1.3.6.1.4.1.1466.115.121.1.21. This method is part of the core schema.

```java
public static Syntax getEnhancedGuideSyntax()
Returns a reference to the `Enhanced Guide Syntax` which has the OID `1.3.6.1.4.1.1466.115.121.1.21`.

Returns:
    A reference to the `Enhanced Guide Syntax`.
```

--------------------------------

### Backup and Share AM Keystore and Password Files

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/configure-sites

This section describes the necessary steps to make the existing AM keystore infrastructure available to a new instance. It involves backing up the default keystore and password files of the new instance and ensuring the existing site keystores are accessible at the same location.

```text
Back up the new instance’s default keystore and password files in the following locations:
  * `/path/to/openam/security/keystores/`
  * `/path/to/openam/security/secrets/default/`
Ensure that the existing keystores in the site are available in the same location to the new instance. This may mean copying the keystores and their password files, mounting a volume, or others.
Ensure the keystore files configured in the `/path/to/openam/config/boot.json` file are available to the instance.
```

--------------------------------

### UMA Postman Collection Setup

Source: https://docs.pingidentity.com/pingam/7.5/uma-guide/uma-example

Instructions for setting up and importing the UMA Postman collection for PingAM.

```APIDOC
## UMA Postman Collection Setup

### Description
This section outlines the steps to download, install, import, and configure the UMA Postman collection for PingAM. This collection includes REST calls for various UMA operations.

### Steps

1. **Download and install Postman.**
2. **Download the UMA Postman collection.**
3. **Import the collection in Postman:**
   * Go to File > Import … > Upload Files.
   * Select the downloaded collection, click Open, then click Import.
4. **Change the collection variables:**
   * Select the `ForgeRock UMA Collection`.
   * On the Variables tab, update variables such as `URL_base` and `admin_password` to match your AM deployment.
   * Save your changes.

### Collection Folders

*   **Prerequisites**: Contains REST calls for initial AM configuration.
*   **UMA Resource Registration Flow**: Contains REST calls for registering and protecting UMA resources.
*   **UMA Grant Flow**: Contains REST calls for requesting access to resources.
*   **Managing UMA Resources**: REST calls related to the `/uma/resource_set` endpoint.
*   **Managing UMA User Labels**: REST calls for managing UMA user and favorite labels.
*   **Managing UMA Policies**: REST calls related to the `/json/users/{user}/uma/policies` endpoint.
```

--------------------------------

### Example Field Management (Get) - PingAM 7.5 Java API

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/api/jackson/CrestArraySchema

Illustrates how to retrieve the 'example' JSON Schema field from a class implementing the WithExampleSchema interface in the PingAM 7.5 Java API. Returns the example value or null if not defined.

```java
public List<Object> getExample()
```

--------------------------------

### UMA Resource Store Configuration Examples

Source: https://docs.pingidentity.com/pingam/7.5/uma-guide/uma-reference

Demonstrates how to configure the UMA resource store, including specifying the store mode and connection details for external stores.

```properties
Store Mode: Default Token Store
Root Suffix: dc=uma-resources,dc=example,dc=com
Max Connections: 10
```

```properties
Store Mode: External Token Store
SSL/TLS Enabled: true
Connection String(s): uma-ldap1.example.com:389|1|1, uma-ldap2.example.com:389|2|1
Login Id: uid=am-uma-bind-account,ou=admins,dc=uma,dc=example,dc=com
Password: your_password
Heartbeat: 10
```

--------------------------------

### Locate ssoadm and Other Tools

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/install-openam-admin-tools

Lists the binary files available after the setup process, including 'ssoadm', 'ampassword', and 'amverifyarchive', typically found within the 'bin' directory of the unpacked tools.

```bash
$ ls openam/bin/**
openam/bin/ampassword  openam/bin/amverifyarchive  openam/bin/ssoadm
```

--------------------------------

### Start DS Server

Source: https://docs.pingidentity.com/pingam/7.5/uma-guide/prepare-uma-store

Starts the DS server instance, making it ready to store UMA resources. This command is essential after applying necessary LDIF files for UMA data.

```bash
$ /path/to/opendj/bin/start-ds
```

--------------------------------

### Example Policy Advice for Authentication Level

Source: https://docs.pingidentity.com/pingam/7.5/authorization-guide/rest-api-authz-policy-decisions

This JSON snippet shows an example of policy advice that specifies a minimum authentication level requirement for a subject. It is used to guide authorization decisions in PingAM.

```json
{
    "advices": {
        "AuthLevelConditionAdvice": [
            "3"
        ]
    }
}
```

--------------------------------

### Node Metadata Annotation Example (Java)

Source: https://docs.pingidentity.com/pingam/7.5/auth-nodes/core-metadata

An example of the @Node.Metadata annotation for the Timer Start node, specifying its outcome provider, configuration class, and tags for categorization as 'metrics' and 'utilities'.

```java
@Node.Metadata(outcomeProvider = SingleOutcomeNode.OutcomeProvider.class,
        configClass = TimerStartNode.Config.class,
        tags = {"metrics", "utilities"})
```

--------------------------------

### LDIF Example with Subrealm Parent Entries

Source: https://docs.pingidentity.com/pingam/7.5/setup-guide/prepare-policy-and-application-store

This LDIF example illustrates the beginning of an LDIF file including the base DN, services entry, and parent entries for a subrealm ('mySubRealm'). It shows the hierarchical structure and necessary object classes.

```ldif
dn: dc=example,dc=com
objectClass: top
objectClass: untypedObject
dc: openam
aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;acl "Allow persistent search"; allow (search, read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;acl "Allow server-side sorting"; allow (read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
entryUUID: 5beee9ea-1c31-3129-a8f9-c79da3102f26

dn: ou=services,dc=example,dc=com
objectclass: top
objectclass: organizationalunit
objectclass: sunServiceComponent
ou: services

dn: o=mySubRealm,ou=services,dc=example,dc=com
objectClass: sunRealmService
objectClass: top
o: mySubRealm

dn: ou=services,o=mySubRealm,ou=services,dc=example,dc=com
objectClass: organizationalUnit
objectClass: sunServiceComponent
objectClass: top
ou: services

dn: ou=admins,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
ou: admins
...
```

--------------------------------

### Start Amster in Debug Mode

Source: https://docs.pingidentity.com/pingam/7.5/amster/install-amster

Shows how to start the Amster client in debug mode using the '-d' flag. This mode provides additional output, such as connection handshakes and Groovy calls, which can be useful for troubleshooting.

```bash
$ ./amster -d
```

--------------------------------

### Start Apache Tomcat

Source: https://docs.pingidentity.com/pingam/7.5/eval-guide/step-1-prepare-server

Executes the startup script for Apache Tomcat to launch the application server. The server's startup time is logged in catalina.out.

```bash
/path/to/tomcat/bin/startup.sh
```

--------------------------------

### Compare boot.json files for AM site configuration

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/configure-sites

This snippet explains how to compare the `/path/to/openam/config/boot.json` bootstrap file of a newly installed AM instance with that of a running instance to ensure it's appropriate for the environment. It also covers scenarios where the file might not be created during installation and the need to copy it from another instance.

```text
Compare the `/path/to/openam/config/boot.json` bootstrap file with that of a running instance. You must ensure that the newly installed instance’s bootstrap file is appropriate for your environment.

The `boot.json` file does not exist in the new instance
Depending on the configuration of the AM keystore in the site, the installation process may not create the bootstrap file.
If so, copy the bootstrap file from another instance and continue with the procedure.
Unless your environment has a requirement to configure the AM keystore in a different location on each instance, it is likely that the bootstrap file should be the same across the site.
If you are overriding the start up settings:
     * Ensure you have copied the customized bootstrap file from another instance in the site.
     * Ensure you are overwriting the existing bootstrap file with your modified file prior to every AM restart.
```

--------------------------------

### Execute AM Silent Installation

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/silent-install

Runs the AM configurator tool in silent mode using a specified properties file. This command initiates the installation process, including configuration store setup and OpenDJ extraction. Additional runtime options like license acceptance and SSL trust store configuration can be provided.

```bash
java -jar openam-configurator-tool-14.1.3.28.jar --file config.properties
```

--------------------------------

### Start Secrets Store Type

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/PluginTools

Installs and registers a secrets store type for service secrets. This method should only be called on plugin startup.

```Java
void startSecretsStoreType(Class<?> secretsStoreClass) throws PluginException
```

--------------------------------

### Install Identity Repository

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/PluginTools

Installs a new identity repository.

```Java
void installIdRepo(Class<?> idRepoConfig)
```

--------------------------------

### WithExampleSchema Interface

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/api/jackson/WithExampleSchema

This section details the methods available for the WithExampleSchema interface, including getting and setting the example field.

```APIDOC
## WithExampleSchema Interface

### Description
Extension for CREST and OpenAPI schemas to express an example value.

### Type Parameters
* `T` - The type of the example.

### Implementing Classes
* `CrestAnySchema`
* `CrestArraySchema`
* `CrestBooleanSchema`
* `CrestObjectSchema`

## Methods

### getExample

#### Description
Gets the `example` JSON Schema field.

#### Method
GET

#### Endpoint
`/schemas/example`

#### Response
* **example** (T) - The example value, or null if not defined.

#### Response Example
```json
{
  "example": "some_example_value"
}
```

### setExample

#### Description
Sets the `example` JSON Schema field.

#### Method
POST

#### Endpoint
`/schemas/example`

#### Parameters
* **example** (String) - Required - The example value.

#### Request Body
```json
{
  "example": "new_example_value"
}
```

#### Throws
* `IOException` - When the type of schema cannot be parsed from the String value.

```

--------------------------------

### Configure IBM Java Options in setup Script

Source: https://docs.pingidentity.com/pingam/7.5/install-guide/install-openam-admin-tools

Demonstrates how to add specific Java system properties to the 'setup' script when using IBM Java. These properties are crucial for cryptography and key generation with IBMJCE.

```bash
$ tail setup
CLASSPATH="$CLASSPATH:resources"

$JAVA_HOME/bin/java -D"load.config=yes" \
-D"help.print=$help_print" \
-D"path.AMConfig=$path_AMConfig" \
-D"path.debug=$path_debug" \
-D"path.log=$path_log" \
-D"amCryptoDescriptor.provider=IBMJCE" \
-D"amKeyGenDescriptor.provider=IBMJCE" \
-cp "$CLASSPATH" \
com.sun.identity.tools.bundles.Main
```

--------------------------------

### ECPFactory - Get Instance

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/com/sun/identity/saml2/ecp/ECPFactory

Retrieves a singleton instance of the ECPFactory. This is the primary method to start interacting with the factory.

```APIDOC
## GET ECPFactory/getInstance

### Description
Returns an instance of the `ECPFactory` Object.

### Method
GET

### Endpoint
ECPFactory/getInstance

### Parameters
None

### Request Example
```
GET ECPFactory/getInstance
```

### Response
#### Success Response (200)
- **ECPFactory** (Object) - An instance of the ECPFactory object.

#### Response Example
```json
{
  "instance": "ECPFactory object"
}
```
```

--------------------------------

### Example Multiple Connection Strings for External Data Stores

Source: https://docs.pingidentity.com/pingam/7.5/reference/deployment-configuration-reference

Demonstrates how to provide multiple comma-separated connection strings for external data stores, prioritizing connections.

```text
uma-ldap1.example.com:389|1|1, uma-ldap2.example.com:389|2|1
```

--------------------------------

### Install Identity Repository

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/PluginTools

Installs a new identity repository. This method should be called during plugin installation and startup. It requires an `IdRepoConfig` annotated class and may throw `PluginException` or `IllegalArgumentException`.

```java
void installIdRepo(Class<?> idRepoConfig) throws PluginException
```

--------------------------------

### Get Subsequence from Start (Java)

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/json/resource/ResourcePath

Returns a new resource path representing a subsequence starting from the first element (index 0) up to, but not including, the specified endIndex. The length of the returned path is equal to endIndex. This is equivalent to subSequence(0, endIndex).

```Java
public ResourcePath head(int endIndex)
Returns a resource path which is a subsequence of the path elements contained in this resource path beginning with the first element (0) and ending with the element at position `endIndex-1`. The returned resource path will therefore have the size `endIndex`. Calling this method is equivalent to:
```
 subSequence(0, endIndex);
 
```

Parameters:
    `endIndex` - The end index, exclusive. 

Returns:
    A resource path which is a subsequence of the path elements contained in this resource path. 

Throws:
    `IndexOutOfBoundsException` - If `endIndex` is bigger than `size()`.
```

--------------------------------

### Get SSL Context

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/opendj/security/SslOptions

Returns the SSLContext that should be used when installing the SSL layer. This context holds configuration for SSL/TLS connections.

```java
public SSLContext sslContext()
```

--------------------------------

### Java @ExampleValue Annotation for Attribute Example Values

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/sm/annotations/adapters/ExampleValue

The @ExampleValue annotation is used to define a default or example string value for an attribute. This value is typically displayed to users in the UI to guide them when filling out configuration fields. It is retained at runtime and applicable to methods.

```Java
@SupportedAll @Retention(RUNTIME) @Target(METHOD) public @interface ExampleValue
An annotation to specify an example value for the attribute.
  * ## Optional Element Summary
Optional Elements
Modifier and Type
Optional Element
Description
`String`
`value`
The example value.


  * ## Element Details
    * ### value
String value
The example value. Typically the example value is used on the UI as a blurred text to aid the user fill the configuration. 

Returns:
    the example value for the attribute. 

Default:
    ""

```

--------------------------------

### Connection String Examples for External DS

Source: https://docs.pingidentity.com/pingam/7.5/reference/deployment-configuration-reference

Provides examples of connection strings for external directory servers, illustrating active/passive and affinity deployments with host, port, server ID, and site ID configurations.

```text
cts-dj1.example.com:389,cts-dj2.example.com:389
cts-dj1.example.com:389|1|1,cts-dj2.example.com:389|2|1
cts-dj1.example.com:389|1|1,cts-dj2.example.com:389|1|1,cts-dj3.example.com:389|1|2
cts-dj1.example.com:389,cts-dj2.example.com:389,cts-dj3.example.com:389,cts-dj4.example.com:389
```

--------------------------------

### Get Authorization ID

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/opendj/ldap/controls/AuthorizationIdentityResponseControl

Retrieves the authorization ID of the user associated with this control. The format can vary, typically starting with 'dn:' or 'u:'.

```Java
public String getAuthorizationId()
// Returns the authorization ID of the user. The authorization ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
// Returns: The authorization ID of the user.
```

--------------------------------

### AbstractNodeAmPlugin Java Class Structure

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/auth/node/api/AbstractNodeAmPlugin

Provides the basic structure and methods for creating authentication nodes, including plugin installation and startup handling.

```java
public abstract class AbstractNodeAmPlugin extends Object implements AmPlugin {
    protected PluginTools pluginTools;

    public AbstractNodeAmPlugin() {
    }

    @Deprecated
    protected Iterable<? extends Class<? extends Node>> getNodes() {
        // Deprecated in favour of getNodesByVersion()
        return null;
    }

    protected Map<String, Iterable<? extends Class<? extends Node>>> getNodesByVersion() {
        // Retrieve the Map of list of node classes that the plugin is providing.
        return null;
    }

    public void onInstall() {
        // Handle plugin installation.
    }

    public void onStartup(org.forgerock.openam.plugins.StartupType startupType) {
        // Handle plugin startup.
    }

    public void setPluginTools(PluginTools pluginTools) {
        // Guice setter for pluginTools.
    }

    public void upgrade(String fromVersion) {
        // This method will be called when the version returned by AmPlugin.getPluginVersion() is higher than the version already installed.
    }
}
```

--------------------------------

### Get EnhancedGuide Syntax Reference

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/opendj/ldap/schema/CoreSchema

Retrieves a reference to the `Enhanced Guide Syntax`, identified by the OID `1.3.6.1.4.1.1466.115.121.1.21`. This is a static method.

```Java
static Syntax getEnhancedGuideSyntax()
Returns a reference to the `Enhanced Guide Syntax` which has the OID `1.3.6.1.4.1.1466.115.121.1.21`.
```

--------------------------------

### HTTP 429 Too Many Requests Response Example

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/http/protocol/Status

Presents an example HTTP response for the 429 (Too Many Requests) status code, used for rate limiting. The response may include details about the condition and a Retry-After header to guide the client on when to resend requests.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: text/plain

Too many requests. Please try again in 60 seconds.
```

--------------------------------

### LDIF Example with Base DN and Services Entry

Source: https://docs.pingidentity.com/pingam/7.5/setup-guide/prepare-policy-and-application-store

This LDIF example demonstrates the structure of the beginning of an LDIF file after including the base DN and the 'ou=services' entry. It includes access control instructions (ACI) and entry UUID for the base DN.

```ldif
dn: dc=example,dc=com
objectClass: top
objectClass: untypedObject
dc: openam
aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;acl "Allow persistent search"; allow (search, read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;acl "Allow server-side sorting"; allow (read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
entryUUID: 5beee9ea-1c31-3129-a8f9-c79da3102f26

dn: ou=services,dc=example,dc=com
objectclass: top
objectclass: organizationalunit
objectclass: sunServiceComponent
ou: services

dn: ou=admins,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
ou: admins
...
```

--------------------------------

### PluginTools methods for starting identity repositories

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/openam/plugins/class-use/PluginException

This snippet details the `startIdRepo` method from `PluginTools` in `org.forgerock.openam.plugins`. This method is used to start an existing identity repository and can throw a `PluginException`.

```java
void PluginTools.startIdRepo(Class<?> idRepoConfig)
```

--------------------------------

### Java: Get List Iterator at Index

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/util/LazyList

Returns a list iterator over the elements in this list in proper sequence, starting at the specified position.

```java
public ListIterator<E> listIterator(int index)

```

--------------------------------

### Java: Get List Iterator

Source: https://docs.pingidentity.com/pingam/7.5/_attachments/apidocs/org/forgerock/util/LazyList

Returns a list iterator over the elements in this list in proper sequence. The iterator starts at the beginning of the list.

```java
public ListIterator<E> listIterator()

```

--------------------------------

### Sample Authentication Logic in Java

Source: https://docs.pingidentity.com/pingam/7.5/authentication-guide/about-authentication-modules-and-chains

This Java code implements a sample authentication process, handling different states like BEGIN, AUTH, and ERROR. It interacts with callbacks to retrieve username and password, validates credentials, and manages error messages. Dependencies include OpenAM's authentication framework and callback handling utilities.

```java
debug.debug("SampleAuth::process state: {}", state);

        switch (state) {

            case STATE_BEGIN:
                // Intialize Callback list if used in chain with
                // iplanet-am-auth-shared-state-enabled=true
                setForceCallbacksRead(true);
                forceCallbacksInit();

                // No time wasted here - simply modify the UI and
                // proceed to next state
                substituteUIStrings();
                return STATE_AUTH;

            case STATE_AUTH:
                // Get data from callbacks. Refer to callbacks XML file.
                NameCallback nc = (NameCallback) callbacks[0];
                PasswordCallback pc = (PasswordCallback) callbacks[1];
                String username = nc.getName();
                String password = String.valueOf(pc.getPassword());

                //First errorstring is stored in "sampleauth-error-1" property.
                if (ERROR_1_USERNAME.equals(username)) {
                    setErrorText(SAMPLE_AUTH_ERROR_1);
                    return STATE_ERROR;
                }

                //Second errorstring is stored in "sampleauth-error-2" property.
                if (ERROR_2_USERNAME.equals(username)) {
                    setErrorText(SAMPLE_AUTH_ERROR_2);
                    return STATE_ERROR;
                }

                if (USERNAME.equals(username) && PASSWORD.equals(password)) {
                    debug.debug("SampleAuth::process User '{}' " +
                            "authenticated with success.", username);
                    return ISAuthConstants.LOGIN_SUCCEED;
                }

                throw new InvalidPasswordException("password is wrong",
                        USERNAME, isReturningPrincipalAsDn());

            case STATE_ERROR:
                return STATE_ERROR;
            default:
                throw new AuthLoginException("invalid state");
        }
    }

    @Override
    public Principal getPrincipal() {
        return new SampleAuthPrincipal(USERNAME);
    }

    private void setErrorText(String err) throws AuthLoginException {
        // Receive correct string from properties and substitute the
        // header in callbacks order 3.
        substituteHeader(STATE_ERROR, bundle.getString(err));
    }

    private void substituteUIStrings() throws AuthLoginException {
        // Get service specific attribute configured in OpenAM
        String ssa = CollectionHelper.getMapAttr(options, "specificAttribute");

        // Get property from bundle
        String new_hdr = ssa + " " +
                bundle.getString("sampleauth-ui-login-header");
        substituteHeader(STATE_AUTH, new_hdr);

        replaceCallback(STATE_AUTH, 0, new NameCallback(
                bundle.getString("sampleauth-ui-username-prompt")));
        replaceCallback(STATE_AUTH, 1, new PasswordCallback(
                bundle.getString("sampleauth-ui-password-prompt"), false));
    }
```
Tokens:
Raw