Signing on to and configuring the administrative console
After you install the PingDirectory server, access the administrative console to verify the configuration and manage the server.
About this task
The administrative console is designed primarily for system configuration, which includes the creation of new schema elements like attribute types and objectClasses. Most entry-monitoring tasks, such as searching and modifying, must be executed with the built-in command-line tools. For more information, see Managing entries.
For more information, see Configuring a global administrator.
Steps
-
Start the PingDirectory server.
$ bin/start-server
-
To access the administrative 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 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.
The root user distinguished name (DN) or the common name of a root user DN is required to sign on to the administrative console. For example, if the DN created when the server was installed is
cn=Directory Manager
, you can usedirectory manager
to sign on to the administrative console. -
Click Sign In.
To set up an SSO connection to the administrative console, see Single sign-on with the administrative console.
To run the administrative console in an external container, such as Tomcat, see Deploying the administrative console.
Setting the administrative console session timeout window
About this task
The default session timeout for the administrative 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 aninit
parameter either in the console or on the command line:Choose from:
-
Use the administrative console:
-
Ensure that the Show Advanced Configuration check box is selected.
-
In the Web Services and Applications list, select Web Application Extensions.
-
In the Web Application Extension list, select Console.
-
In the Init Parameter field, enter the desired timeout duration value in seconds.
-
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 administrative 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 administrative console as a standalone instance. Running the console as a standalone instance also allows you to make changes to the console without restarting the directory server’s HTTPS connection handlers.
For more information on deployment options, click the following tabs.
-
Use Docker to run a standalone console
-
Set up the console in a Tomcat environment
Using Docker to run a standalone administrative console
About this task
The administrative 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 administrative 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 administrative 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 console image in a local Docker deployment with the console listening on port
8443
using thepingnet
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 console outside of Docker on port9443
, for example, use9443:8443
. -
To access the 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 administrative console on a Tomcat environment
Before you begin
To set up a standalone console, you need the admin-console.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.
Because Tomcat server version 10 has a defect with Spring Boot applications, use Tomcat 9 instead. |
Steps
-
Download the Tomcat 9
.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 theTomcat_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
admin-console.war
file into thewebapps
folder in the Tomcat root directory. -
To start the Tomcat server, run
startup.sh
orstartup.bat
from thebin
folder of the Tomcat root directory.Result:
Tomcat automatically extracts the console from the compressed
.war
file into an exploded application directory and starts running the console. -
To access the console, use the
admin-console
path from the Tomcat server path.By default, the path to access the console is
localhost:8080/admin-console
.
Configuring the administrative console
About this task
After you have deployed the PingDirectory administrative console, you can configure it.
Steps
-
Disable the embedded administrative console using
dsconfig
or the administrative console to configure connection handlers:Choose from:
-
To use
dsconfig
, rundsconfig 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 administrative console.
-
To use the administrative console, open the console:
-
On the Configuration page, go to Connection Handlers.
-
In the Connection Handlers list, select the HTTP or HTTPS connection handler that is hosting the administrative console.
-
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 administrative console’s
application.yml
file.You can configure the standalone PingDirectory server administrative console by modifying the
/tmp/Console/WEB-INF/classes/application.yml
file. To see the different configuration settings listed in the defaultapplication.yml
file included with the administrative console and what they do, expand the following table.Configuration settings
Setting Description spring.*
For information about these properties, see the .spring.io/spring-boot/docs/current/reference/html/application-properties.html//Spring API docs].
You should not modify them.
management.server.base-path
Controls the prefix of the Spring Boot Actuator endpoints of the 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 console logs messages to a file.log.file
If logging is enabled, this specifies the file that the console will log to.
PingData.SSO.OIDC.enabled
If this is set to
true
, the console attempts to use OpenID Connect (OIDC) single sign-on (SSO) to bind to the managed server.If
false
, the 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 console requires a matching host name on the OIDC provider certificate.PingData.SSO.OIDC.trust-all
If this is set to
true
, the console accepts any OIDC provider certificate.PingData.SSO.OIDC.username-attributes
The LDAP attribute containing the username of the user the 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 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 console has a button that has the managed directory server run acollect-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
, andfavicon.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
, andexpert
.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 console for your changes to take effect. -
Select servers to manage in the administrative console:
-
To use the
application.yml
file to select a server for the administrative console to manage:-
Set the
ldap.server
property to the address of the LDAP server to bind to. -
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
-
-
To switch between managed servers in a single topology while signed on to the administrative console, in the Servers list, select the server that you want to manage.
-
To select a server when SSO is not enabled and the
login.hide-server
property inapplication.yml
isfalse
:-
If you are signed on to the console, sign off of your current session.
-
Change the Server field value on the console sign-on page to the address of the LDAP server you want to manage.
-
-
To select a server when SSO is enabled:
-
Enter the console URL with the
ldap-hostname
andldaps-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-hostname
is <ldap.host>, and the <ldaps-port> is 636
.