--- title: Signing on to and configuring the admin console description: Sign on to the PingDirectory admin console and deploy, configure, or customize it for your environment. component: pingdirectory version: 10.3 page_id: pingdirectory:pingdirectory_server_administration_guide:pd_ds_sign_on_admin_console canonical_url: https://docs.pingidentity.com/pingdirectory/11.1/pingdirectory_server_administration_guide/pd_ds_sign_on_admin_console.html llms_txt: https://docs.pingidentity.com/pingdirectory/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2024-08-20T00:00:00Z page_aliases: ["pd_sync_setting_admin_console_timeout.adoc", "pd_ds_deploy_admin_console.adoc", "pd_ds_configure_admin_console.adoc", "pd_ds_docker_standalone_admin_console.adoc", "pd_ds_setup_admin_console_tomcat.adoc", "pd_ds_customizetext_ds.adoc", "pd_ds_customizecolor_ds.adoc", "pd_ds_customizeicon_ds.adoc", "pd_ds_use_custom_rebranding.adoc"] superseded_by: https://docs.pingidentity.com/pingdirectory/11.1/pingdirectory_server_administration_guide/pd_ds_sign_on_admin_console.html section_ids: about-this-task: About this task steps: Steps setting-the-admin-console-session-timeout-window: Setting the admin console session timeout window about-this-task-2: About this task steps-2: Steps choose-from: Choose from: choose-from-2: Choose from: deploying_admin_console: Deploying the admin console using-docker-to-run-a-standalone-admin-console: Using Docker to run a standalone admin console about-this-task-3: About this task steps-3: Steps example: Example: setting-up-the-admin-console-on-a-tomcat-server: Setting up the admin console on a Tomcat server before-you-begin: Before you begin about-this-task-4: About this task steps-4: Steps result: Result: example-2: Example: configuring-the-admin-console: Configuring the admin console about-this-task-5: About this task steps-5: Steps choose-from-3: Choose from: example-3: Example: example-4: Example: using-custom-rebranding: Using custom rebranding about-this-task-6: About this task steps-6: Steps customizing-text-information: Customizing text information about-this-task-7: About this task steps-7: Steps customizing-the-color-scheme-or-logos: Customizing the color scheme or logos about-this-task-8: About this task steps-8: Steps customizing-the-page-icon: Customizing the page icon about-this-task-9: About this task steps-9: Steps --- # 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](pd_ds_manage_entries.html). ## Steps 1. Start the PingDirectory server. `$ bin/start-server` 2. To access the admin console, go to https\://*\*:*\*/console/login. *\* is the host name of the server, and *\* is the port on which the server accepts connections from HTTPS clients. The host name and port were configured during installation. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The `` 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. | 3. 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](_images/qtl1667934154226.png) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The root user distinguished name (DN) *(tooltip: \
\

A name uniquely identifying an object within the hierarchy of a directory tree.\

\
)* 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. | 4. Click **Sign In**. To set up an SSO connection, refer to [Single sign-on with the admin console](pd_ds_sso_admin_console.html). To run the console in an external container, such as Tomcat, refer to [Deploying the admin console](#deploying_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 1. 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. ![A screen capture of the admin console configuration screen with the Show Advanced Configuration check box selected.](_images/mrb1652811812233.png) 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= ``` 2. 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 "" \ --set enabled:false dsconfig set-connection-handler-prop \ --handler-name "" \ --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](https://hub.docker.com/r/pingidentity/pingdataconsole). To see a `docker-compose` example that deploys a PingDirectory container with a corresponding console, see the [PingDirectory getting started demo](https://github.com/pingidentity/pingidentity-devops-getting-started/blob/master/11-docker-compose/00-standalone/pingdirectory/docker-compose.yaml). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The [Ping Identity Helm charts](https://helm.pingidentity.com/) 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: ```shell 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\://*\*:*\*/console/login and enter the following credentials. | Field | Credential | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Server** | `:` 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 1. Download the Tomcat 11 `.zip` archive from the [Apache Tomcat downloads page](https://tomcat.apache.org/download-11.cgi). 2. Extract the `.zip` archive. 3. To set up the Tomcat server, follow the instructions in the `RUNNING.txt` file from the extracted directory. 4. 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: ``` ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This information is sourced from the [Smart Scanner](https://www.thesmartscanner.com/vulnerability-list/server-version-disclosure) website, where you can learn more about this Tomcat server vulnerability. | 5. Copy the `.war` file into the `webapps` folder in the Tomcat root directory. 6. 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. 7. 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 1. 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 "" \ --reset web-application-extension ``` | | | | - | -------------------------------------------------------------------------------------------------------- | | | Replace *\* 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. 2. To finalize your changes, restart the HTTPS Connection Handler using `dsconfig`: #### Example: ``` dsconfig set-connection-handler-prop \ --handler-name "" \ --set enabled:false dsconfig set-connection-handler-prop \ --handler-name "" \ --set enabled:true ``` 3. 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. > **Collapse: Configuration settings** > > | Setting | Description | > | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | `spring.*` | Learn more about these properties in the [Spring API docs](https://docs.spring.io/spring-boot/appendix/application-properties/index.html).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) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* single sign-on (SSO) *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* 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. | 4. 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 "" \ --set enabled:false dsconfig set-connection-handler-prop \ --handler-name "" \ --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. ![A screen capture of the PingDirectory admin console Servers list.](_images/ach1639506426462.png) 3. To select a server when SSO *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* 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://:/console/login?ldap-hostname=&ldaps-port=` #### Example: In the following example URL, *\* is `localhost`, *\* is `443`, *\* is `ldap.host`, and *\* 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 1. To customize the admin console, open the `application.yml` file and set *\* 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. 2. 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= ``` ### Customizing text information #### About this task To customize text information, such as contact information or company names: #### Steps 1. Make a copy of the `branding.properties.template` file and rename it to `branding.properties`. 2. Make the desired changes to the copy. 3. Place the copy in the folder specified by the *\* setting. 4. 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 1. Make a copy of the `branding.css.template` file and rename it to `branding.css`. 2. Make the desired changes. 3. Place the copy in the folder specified by the *\* setting. ### Customizing the page icon #### About this task To customize the page icon used by the admin console: #### Steps 1. Name the desired icon `favicon.ico`. | | | | - | ---------------------------------- | | | The icon must be in `.ico` format. | 2. Place `favicon.ico` in the folder specified by the *\* setting.