--- title: Start here description: Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI. component: pingidm version: 8.1 page_id: pingidm:samples-guide:start-here canonical_url: https://docs.pingidentity.com/pingidm/8.1/samples-guide/start-here.html keywords: ["Samples", "Configuration"] section_ids: running-samples: Run the samples preparing-openidm: Prepare IDM ldap-server-config: LDAP server configuration start_ds_using_sample_ldif_data: Start DS using sample LDIF data --- # Start here | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Starting with IDM 8.1, the [legacy admin UI is deprecated](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.forgerock.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | Before you try any of the samples read [Run the Samples](#running-samples) and [Prepare IDM](#preparing-openidm). For any samples that require an LDAP server, refer to [LDAP Server Configuration](#ldap-server-config). ## Run the samples Each sample directory in `openidm/samples/` contains a number of subdirectories, such as `conf/` and `script/`. To start IDM with a sample configuration, navigate to the `/path/to/openidm` directory and use the `-p` option of the `startup` command to point to the sample whose configuration you want to use. Some samples require additional software, such as an external LDAP server or database. Many of the procedures in this guide refer to paths such as `samples/sample-name`. In each of these cases, the complete path is assumed to be `/path/to/openidm/samples/sample-name`. When you move from one sample to the next, you are changing the IDM configuration. For more information, refer to [Configuration changes](../setup-guide/changing-configuration.html). The command-line examples in the IDM documentation assume a UNIX shell. To run the samples on Windows, adjust the commands, as necessary. ## Prepare IDM Install an instance of IDM specifically to experiment with the samples and easily discard the result when you finish. If you are using the same IDM instance for multiple samples, clear the repository between samples. To do so, shut down IDM and delete the `openidm/db/openidm` directory: ```bash rm -rf /path/to/openidm/db/openidm ``` ## LDAP server configuration For samples in this guide that require an LDAP server, Ping recommends using PingDS (DS). > **Collapse: Sample LDAP Server Configuration** > > * The LDAP server runs on the local host. > > * The LDAP server listens on port 1389. > > * The replication port is 8989. > > Servers with replication ports maintain a changelog for their own use. The changelog is exposed over LDAP under the base DN, `cn=changelog`. For samples that demonstrate liveSync with an LDAP server, you *must* configure a replication port when you set up DS. For ease of use, all the LDAP samples assume that you have configured a replication port, even if you don't use liveSync. > > * A user with DN `uid=admin` and password `password` has read access to the LDAP server. > > * Directory data for that server is stored under base DN `dc=com`. > > * User objects for that server are stored under base DN `ou=People,dc=example,dc=com`. > > * User objects have the object class `inetOrgPerson`. > > * User objects have the following attributes: > > * `cn` > > * `description` > > * `givenName` > > * `mail` > > * `sn` > > * `telephoneNumber` > > * `uid` > > * `userPassword` > > > **Collapse: Example User Object** > > > > ```ldif > > dn: uid=bjensen,ou=People,dc=example,dc=com > > objectClass: person > > objectClass: organizationalPerson > > objectClass: inetOrgPerson > > objectClass: top > > givenName: Barbara > > uid: bjensen > > cn: Barbara Jensen > > telephoneNumber: 1-360-229-7105 > > sn: Jensen > > mail: bjensen@example.com > > description: Created for OpenIDM > > userPassword: password > > ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you are using the same DS instance for multiple samples, delete the DS configuration between samples:1) Shutdown DS: ``` /path/to/opendj/bin/stop-ds --quiet ``` 2) Delete the `opendj/db` directory: ``` rm -rf /path/to/opendj/db ``` 3) Delete the `opendj/config` directory: ``` rm -rf /path/to/opendj/config ``` | ### Start DS using sample LDIF data Samples that use an LDAP server require existing user data. The example procedure below corresponds to the `sync-with-ldap` sample and imports user data (`openidm/samples/sync-with-ldap/data/Example.ldif`) during DS setup. For other samples, replace or remove the path to the sample data, as necessary. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The following procedure provides setup instructions for DS 8.1. For older versions of DS, or an alternative LDAP server, modify the instructions, as necessary. | 1. Download the [DS and IDM .zip archives](https://backstage.forgerock.com/downloads). 2. Extract the .zip archives. 3. Generate a DS *deploymentId* for DS setup and deployment management: ``` /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password your-deployment-ID ``` 4. Start DS: ``` /path/to/opendj/setup \ --serverId evaluation-only \ --deploymentId your-deployment-ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword password \ --hostname localhost \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --replicationPort 8989 \ --httpPort 8090 \ --profile ds-user-data:7.0.0 \ --set ds-user-data/baseDn:dc=com \ --set ds-user-data/ldifFile:/path/to/openidm/samples/sync-with-ldap/data/Example.ldif \ --acceptLicense \ --start ... Validating parameters..... Done Configuring certificates..... Done Configuring server..... Done Configuring profile DS user data store......... Done Starting directory server............... Done To see basic server status and configuration, you can launch /path/to/opendj/bin/status ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Every DS deployment requires a *deploymentId* and a *deploymentIdPassword* to secure network connections. The deploymentId is a random string generated by DS software. The deploymentIdPassword is a secret string that you choose. It must be at least 8 characters long. The deploymentId and deploymentIdPassword automate key pair generation and signing without storing the CA private key. For more information, refer to [Deployment IDs](https://docs.pingidentity.com/pingds/8.1/security-guide/pki.html#about-deployment-keys) in the *DS Security Guide*. | 5. Import the DS CA certificate into the IDM truststore: ``` /path/to/opendj/bin/dskeymgr \ export-ca-cert \ --deploymentId your-deployment-ID \ --deploymentIdPassword password \ --alias dscert \ --keyStoreFile /path/to/openidm/security/truststore \ --keyStorePassword:file /path/to/openidm/security/storepass ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Because each new deployment of DS has a unique deploymentId, the same certificate does not work from one sample to the next. To handle this scenario, do one of the following:- Give each subsequent sample certificate a unique alias. For example: * `--alias dscert1` * `--alias dscert2` * `--alias dscert3` - Delete the old certificate from the trust store: ```bash keytool \ -delete \ -keystore /path/to/openidm/security/truststore \ -alias dscert ``` |