Skip to content

Server Profile Structures

Each of the Docker images use a server profile structure that is specific to each product. The structure (directory paths and data) of the server profile differs between products. Depending on how you Deploy Your Server Profile, it will be pulled or mounted into /opt/in on the container and used to stage your deployment.

The following locations are the server profile structures for each of our products with example usage. For help with an example of the basics, see the pingidentity-server-profiles/getting-started examples.

Ignore .sec directories in examples

In the getting-started profile examples, you should not use the .sec directory when providing passwords to your containers. These examples are only intended for demonstration purposes. Instead, set an environment variable with your secrets or orchestration later:

  PING_IDENTITY_PASSWORD="secret"

PingFederate

See the example at getting-started/pingfederate.

Path Location description
instance Directories and files that you want to be used at product runtime, in accordance with the directory layout of the product.
instance/server/default/data An extracted configuration archive exported from PingFederate.
instance/bulk-config/data.json A JSON export from the PingFed admin API /bulk/export.
instance/server/default/deploy/OAuthPlayground.war Automatically deploy the OAuthPlayground web application.
instance/server/default/conf/META-INF/hivemodule.xml Apply a Hive module config to the container. Used for persisting OAuth clients, grants, and sessions to an external DB.

PingFederate Integeration Kits

By default, PingFederate is shipped with a handful of integration kits and adapters. If you need other integration kits or adapters in the deployment, manually download them and place them inside server/default/deploy of the server profile. You can find these resources in the product download page here.

PingAccess

Example at getting-started/pingaccess.

Path Location description
instance Directories and files that you want to be used at product runtime, in accordance with the directory layout of the product.
instance/conf/pa.jwk Used to decrypt a data.json configuration upon import.
instance/data/data.json PA 6.1+ A config file that, if found by the container, is uploaded into the container.
instance/data/PingAccess.mv.db Database binary that would be ingested at container startup if found.

PingAccess Best Practices

PingAccess profiles are typically minimalist because the majority of PingAccess configurations can be found within a data.json or PingAccess.mv.db file. You should use data.json for configurations and only use PingAccess.mv.db if necessary. You can easily view and manipulate configurations directly in a JSON file as opposed to the binary PingAccess.mv.db file. This fact makes tracking changes in version control easier as well.

PingAccess 6.1.x+ supports using only data.json, even when clustering. However on 6.1.0.3 make sure data.json is only supplied to the admin node.

PingAccess 6.1.0+

PingAccess now supports native data.json ingestion, which is the recommended method. Place data.json or data.json.subst in instance/conf/data/start-up-deployer.

The JSON configuration file for PingAccess must be named data.json.

A data.json file that corresponds to earlier PingAccess versions might be accepted. However, after you are on version 6.1.x, the data.json file will be forward compatible. This support means you are able to avoid upgrades for your deployments!

PingAccess 6.0.x and earlier

The JSON configuration file for PingAccess must be named data.json and located in the instance/data directory.

All PingAccess versions

A corresponding file named pa.jwk must also exist in the instance/conf directory for the data.json file to be decrypted on import. To get a data.json and pa.jwk that work together, pull them both from the same running PingAccess instance.

For example, if PingAccess is running in a local Docker container you can use these commands to export the data.json file and copy the pa.jwk file to your local Downloads directory:

    curl -k -u "Administrator:${ADMIN_PASSWORD}" -H "X-Xsrf-Header: PingAccess" https://localhost:9000/pa-admin-api/v3/config/export -o ~/Downloads/data.json

    docker cp <container_name>:/opt/out/instance/conf/pa.jwk ~/Downloads/pa.jwk

Password Variables

You can find the PingAccess administrator password in PingAccess.mv.db, not in data.json. For this reason, you can use the following environment variables to manage different scenarios:

  • PING_IDENTITY_PASSWORD

    Use this variable if:

    • You're starting a PingAccess container without any configurations.
    • You're using only a data.json file for configurations.
    • Your PingAccess.mv.db file has a password other than the default "2Access".

    The PING_IDENTITY_PASSWORD value will be used for all interactions with the PingAccess Admin API (such as importing configurations and creating clustering).

  • PA_ADMIN_PASSWORD_INITIAL

    Use this variable in addition to PING_IDENTITY_PASSWORD to change the runtime admin password and override the password in PingAccess.mv.db.

    If you use only data.json and do notpass PING_IDENTITY_PASSWORD, the password will default to "2FederateM0re". Always use PING_IDENTITY_PASSWORD.

Ping Data Products

The Ping Data Products (PingDirectory, PingDataSync, PingAuthorize, PingDirectoryProxy) follow the same structure for server-profiles.

Example at getting-started/pingdirectory.

Path Location description
pd.profile Server profile matching the structure as defined by PingDirectory Server Profiles
instance Directories and files that you want to be used at product runtime, in accordance with the layout of the product. In general, this should be non existing or empty.
env-vars You can set environment variables used during deployment. See Variables and Scope for more info. In general, this should be non existing or empty.
extensions You can provide URLs to download Server SDK extensions in a remote.list file. See Including Extensions in PingData Server Profiles for more info.

Ping Data Server Profile Best Practices

  • In most circumstances, the pd.profile directory should be the only directory in the server profile.
  • All environment variables should be provided through Kubernetes configmaps/secrets and a secret management tool. Be careful providing an env-vars and if you do, please review Variables and Scope

Creating a pd.profile from scratch

Use the manage-profile tool (found in product bin directory) to generate a pd.profile from an existing Ping Data 8.0+ deployment. An example on creating this pd.profile looks like:

manage-profile generate-profile --profileRoot /tmp/pd.profile
rm /tmp/pd.profile/setup-arguments.txt

Follow the instructions provided when you run the generate-profile to ensure that you include any additional components, such as encryption-settings.