Signing on to and configuring the admin console

After you install the PingDirectory server, access the admin console to verify the configuration and manage the server.

About this task

The admin console is designed primarily for system configuration, which includes the creation of new schema elements like attribute types and object classes. Most entry-monitoring tasks, such as searching and modifying, must be executed with the built-in command-line tools. Learn more in Managing entries.

Steps

Start the PingDirectory server.

$ bin/start-server
To access the admin console, go to https://<host>:<port>/console/login.

<host> is the host name of the server, and <port> is the port on which the server accepts connections from HTTPS clients. The host name and port were configured during installation.

The <port> is different for PingDirectory and each of its add-ons. The admin console that you access is specific to the add-on for which you are using it.

In the Username and Password fields, enter the root user DN credentials.

Screen capture of the PingDirectory admin console sign-on screen showing the Server, Username, and Password fields

The root user distinguished name (DN) or the common name of a root user DN is required to sign on to the admin console. For example, if the DN created when the server was installed is cn=Directory Manager, you can use directory manager to sign on.

Click Sign In.

To set up an SSO connection, refer to Single sign-on with the admin console.

To run the console in an external container, such as Tomcat, refer to Deploying the admin console.

Setting the admin console session timeout window

About this task

The default session timeout for the admin console is 24 hours. You can adjust your session length to suit your organization’s needs.

When the session duration is exceeded, all inactive users are logged off automatically.

To change the default session timeout value:

Steps

To configure the server.sessionTimeout application parameter, which specifies the timeout duration in seconds, set the value as an init parameter either in the console or on the command line:

Choose from:
- Use the admin console:
  1. Ensure that the Show Advanced Configuration check box is selected.
  2. In the Web Services and Applications list, select Web Application Extensions.
  3. In the Web Application Extension list, select Console.
  4. In the Init Parameter field, enter the desired timeout duration value in seconds.
  5. Click Save.
- Use the command line to run the following:
  dsconfig set-web-application-extension-prop --no-prompt \ --extension-name Console \ --add init-parameter:server.sessionTimeout=<value in seconds>

To save your changes, restart the HTTP Connection Handler or the server:

Choose from:

Restart the HTTP Connection Handler:

dsconfig set-connection-handler-prop \
    --handler-name "<HTTPS Connection Handler>" \
    --set enabled:false

dsconfig set-connection-handler-prop \
    --handler-name "<HTTPS Connection Handler>" \
    --set enabled:true

Restart the server using bin/stop-server with the -R or --restart option:
```
bin/stop-server --restart
```

Deploying the admin console

To administer multiple servers from a single console instance, you can use Docker or a Java application server, such as Tomcat or Jetty, to run the admin console as a standalone instance. Running the admin console as a standalone instance also allows you to make changes to the console without restarting the directory server’s HTTPS connection handlers.

Learn more about deployment options in the following sections.

Using Docker to run a standalone admin console

About this task

The admin console is available as a standalone Docker image on Docker Hub. To see a docker-compose example that deploys a PingDirectory container with a corresponding console, see the PingDirectory getting started demo.

The Ping Identity Helm charts also include support for the admin console, which you should use when deploying the console in Kubernetes.

Steps

To connect with a PingDirectory server that is deployed in Docker, run the admin console image in a local Docker deployment.

The network you use must match the network used by the PingDirectory server’s container.

Example:

The following example deploys the standalone admin console image in a local Docker deployment with the console listening on port 8443 using the pingnet network:

docker run \
    --name pingdataconsole \
    --publish 8443:8443 \
    --network pingnet \
    --detach \
    pingidentity/pingdataconsole:edge

You can change the first port in the --publish line based on what port you want to use on your local machine, but you shouldn’t change the second port. To access the admin console outside of Docker on port 9443, for example, use 9443:8443.

To access the admin console, go to https://<hostname>:<port>/console/login and enter the following credentials.

Field Credential

Server

<PingDirectory container name>:<LDAPS port>

The name of the server you enter on the sign-on page must match the name of the PingDirectory container you are trying to connect to along with the LDAPS port of that container.

For example, use pingdirectory:1636 to connect to a standalone PingDirectory Docker container on the same network.

Username

administrator

Password

2FederateM0re

Setting up the admin console on a Tomcat server

Before you begin

To set up a standalone admin console, you need the .war file from the PingDirectory server’s resource/admin-console.zip archive.

About this task

You can use the .war file with Java application servers, such as Tomcat or Jetty. The following example uses Tomcat as the server environment.

Steps

Download the Tomcat 11 .zip archive from the Apache Tomcat downloads page.
Extract the .zip archive.
To set up the Tomcat server, follow the instructions in the RUNNING.txt file from the extracted directory.
To keep the Tomcat server information from being exposed, in the Host section of the Tomcat_directory/conf/server.xml file, add the following line:
```
<Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="true" showServerInfo="false" />
```
This information is sourced from the Smart Scanner website, where you can learn more about this Tomcat server vulnerability.
Copy the .war file into the webapps folder in the Tomcat root directory.
To start the Tomcat server, run startup.sh or startup.bat from the bin folder of the Tomcat root directory.

Result:

Tomcat automatically extracts the admin console from the compressed .war file into an exploded application directory and starts running the console.
To access the admin console, add the name of the .war file to the end of the Tomcat server’s path.

Example:

If the Tomcat server is deployed on localhost:8080, and the .war file is named management-console.war, then the path to access the console is localhost:8080/management-console.

Configuring the admin console

About this task

After you have deployed the PingDirectory admin console, you can configure it.

Steps

Disable the embedded admin console using dsconfig or the admin console to configure connection handlers:

Choose from:
- To use dsconfig, run dsconfig set-connection-handler-prop:
  dsconfig set-connection-handler-prop \ --handler-name "<HTTPS Connection Handler>" \ --reset web-application-extension
  Replace <HTTPS Connection Handler> with the name of the connection handler hosting the admin console.
- To use the admin console, open the console:
  1. On the Configuration page, go to Connection Handlers.
  2. In the Connection Handlers list, select the HTTP or HTTPS connection handler that is hosting the admin console.
  3. Go to Web Application Extension and click the arrows to move Console from the Selected column on the right to the Available column on the left.

To finalize your changes, restart the HTTPS Connection Handler using dsconfig:

Example:

dsconfig set-connection-handler-prop \
    --handler-name "<HTTPS Connection Handler>" \
    --set enabled:false

dsconfig set-connection-handler-prop \
    --handler-name "<HTTPS Connection Handler>" \
    --set enabled:true

Configure the admin console’s application.yml file.

You can configure the standalone PingDirectory server admin console by modifying the /tmp/Console/WEB-INF/classes/application.yml file. To see the different configuration settings listed in the default application.yml file included with the admin console and what they do, expand the following table.

Configuration settings

Setting Description

spring.*

Learn more about these properties in the Spring API docs.

You should not modify them.

management.server.base-path

Controls the prefix of the Spring Boot Actuator endpoints of the admin console application.

You should not modify this setting.

logging.level.*

Controls the severity level of messages logged about these packages.

log.console

If this is set to true, the admin console logs messages to a file.

log.file

If logging is enabled, this specifies the file that the admin console will log to.

PingData.SSO.OIDC.enabled

If this is set to true, the admin console attempts to use OpenID Connect (OIDC) single sign-on (SSO) to bind to the managed server.

If false, the admin console asks for a username and password.

PingData.SSO.OIDC.issuer-uri

The issuer URI to the OIDC provider.

PingData.SSO.OIDC.client-id

The client ID used with the OIDC provider.

PingData.SSO.OIDC.client-secret

The client secret used with the OIDC provider.

PingData.SSO.OIDC.trust-store-file

The file path to the trust store used when communicating with the OIDC provider.

PingData.SSO.OIDC.trust-store-type

The type of trust store specified by PingData.SSO.OIDC.trust-store-file.

PingData.SSO.OIDC.trust-store-pin

Specifies the password used with the trust store specified by PingData.SSO.OIDC.trust-store-file.

PingData.SSO.OIDC.trust-store-pin-environment-variable

Specifies the environment variable containing the password used with the trust store specified by PingData.SSO.OIDC.trust-store-file.

PingData.SSO.OIDC.strict-hostname-verification

If this is set to true, the admin console requires a matching host name on the OIDC provider certificate.

PingData.SSO.OIDC.trust-all

If this is set to true, the admin console accepts any OIDC provider certificate.

PingData.SSO.OIDC.username-attributes

The LDAP attribute containing the username of the user the admin console is logging in as when using SSO.

login.hide-server

If this is set to true, the 'server' field is hidden on the sign on page.

ldap.server

Auto-populates the 'server' field on the sign-on page.

If login.hide-server=true, this value determines which directory server the admin console tries to bind to.

ldap.init-user

Auto-populates the user field on the sign-on page.

ldap.init-password

Auto-populates the password field on the sign-on page.

ldap.trust-store-file

The file path to the trust store used when binding to the directory server.

ldap.trust-store-type

Specifies the type of trust store specified by trust-store-file.

ldap.trust-store-pin

Specifies the password used with the trust store specified by trust-store-file.

ldap.trust-store-pin-environment-variable

Specifies the environment variable containing the password used with the trust store specified by trust-store-file.

ldap.file-servlet-name

Specifies the name of the file servlet on the managed directory server to use when fetching generated collect-support-data (CSD) or server profiles.

ldap.csd-task-enabled

If this is set to true, the admin console has a button that has the managed directory server run a collect-support-data task.

ldap.csd-destination-folder

The file path to the folder where the managed directory server stores generated CSD files after running the collect-support-data task.

ldap.profile-destination-folder

The file path to the folder where the managed directory server stores generated server profiles after running the generate-server-profile task.

Do not change this property.

branding.custom-folder

The file path to the folder that holds custom branding.properties, branding.css, and favicon.ico files.

If empty, default Ping Identity branding is used instead.

configuration.complexity

Determines the maximum complexity level for shown configuration objects.

The possible values are basic, standard, advanced, and expert.

server.sessionTimeout

The amount of time a web session can remain idle before the user must sign on again. The time is set in seconds unless you use a time interval (h for hours or m for minutes). If not specified, the default is 24 hours.

After modifying the application.yml file, you must restart the admin console for your changes to take effect.

Select servers to manage in the admin console:
1. To use the application.yml file to select a server for the admin console to manage:
  1. Set the ldap.server property to the address of the LDAP server to bind to.
  2. Restart the console using the following command:
    
    dsconfig set-connection-handler-prop \ --handler-name "<HTTPS Connection Handler>" \ --set enabled:false dsconfig set-connection-handler-prop \ --handler-name "<HTTPS Connection Handler>" \ --set enabled:true
2. To switch between managed servers in a single topology while signed on to the admin console, in the Servers list, select the server that you want to manage.
3. To select a server when SSO is not enabled and the login.hide-server property in application.yml is false:
  1. If you are signed on to the admin console, sign off of your current session.
  2. Change the Server field value on the console sign-on page to the address of the LDAP server you want to manage.
4. To select a server when SSO is enabled, enter the admin console URL with the ldap-hostname and ldaps-port query parameters specified when accessing the console:
  
  https://<hostname>:<port>/console/login?ldap-hostname=<ldap.host>&ldaps-port=<ldaps-port>
  
  Example:
  
  In the following example URL, <hostname> is localhost, <port> is 443, <ldap.host> is ldap.host, and <ldaps-port> is 636:
  
  https://localhost:443/console/login?ldap-hostname=ldap.host&ldaps-port=636

Using custom rebranding

You can customize several visual elements of the admin console, including branding elements such as contact information or logos.

About this task

You can use the command line to configure the PingDirectory suite of products.

Steps

To customize the admin console, open the application.yml file and set <branding.custom-folder> to a local filepath that is not a subdirectory of the console application directory.

This path should contain the elements for the admin console to display.

Set the custom branding filepath on any admin console in the PingDirectory suite of products by running the following dsconfig command:

dsconfig set-web-application-extension-prop \
    --extension-name Console \
    --set init-parameter:branding.custom-folder=<path to folder>

Customizing text information

About this task

To customize text information, such as contact information or company names:

Steps

Make a copy of the branding.properties.template file and rename it to branding.properties.
Make the desired changes to the copy.
Place the copy in the folder specified by the <branding.custom-folder> setting.
Restart the admin console.

Customizing the color scheme or logos

About this task

To customize the color scheme or logos used by the admin console:

Steps

Make a copy of the branding.css.template file and rename it to branding.css.
Make the desired changes.
Place the copy in the folder specified by the <branding.custom-folder> setting.

Customizing the page icon

About this task

To customize the page icon used by the admin console:

Steps

Name the desired icon favicon.ico.

The icon must be in .ico format.
Place favicon.ico in the folder specified by the <branding.custom-folder> setting.

PingDirectory

Signing on to and configuring the admin console

About this task

Steps

Setting the admin console session timeout window

About this task

Steps

Choose from:

Choose from:

Deploying the admin console

Using Docker to run a standalone admin console

About this task

Steps

Example:

Setting up the admin console on a Tomcat server

Before you begin

About this task

Steps

Result:

Example:

Configuring the admin console

About this task

Steps

Choose from:

Example:

Example:

Using custom rebranding

About this task

Steps

Customizing text information

About this task

Steps

Customizing the color scheme or logos

About this task

Steps

Customizing the page icon

About this task

Steps