PingOne Advanced Services

Creating and updating virtual hosts

You and your administrators can create and update virtual host certificates and TLS configurations yourselves. Configurations are automatically replicated to child regions in PingOne Advanced Services for the following applications:

  • PingFederate

  • PingFederate Admin API

  • PingAccess

  • PingAccess Admin API

  • PingAccess Agents

  • PingDirectory

  • Delegated Admin

Supported functions include:

  • Create/List/Update/Delete configurations

    With the CREATE certificates route, the certificate and key must be formatted into a single line with line-break characters.

    Linux/Unix:

    awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' "cert_or_pkey.pem" | pbcopy

    Windows PowerShell or PowerShell Core:

    (Get-Content -Raw -Path "cert_or_pkey.pem") -replace "`r?`n", '\n' | Set-Clipboard
    The GET certificates route does not return the certificate’s fullchain and private key. It is up to the user to keep track of that information.

    Also note that after you create or update a configuration, it will take some time for the virtual host to become available.

  • Rollback configurations

    Configurations can only be rolled back once. Then the configuration needs to be updated again at least once before rollback will succeed again.

    Rollback routes also support an optional dry_run query parameter. Setting it to true in a request gets the expected version after rollback, but does not do the rollback.

Limitations include:

  • You cannot currently create or update the following items yourself. Submit a service request instead.

    • MTLS configurations

    • Configurations that need custom annotations, such as “cors-all-origin”

    • Private Ingress configurations

    • EC or ECC TLS certificates

  • You cannot currently create or update PingFederate Admin UI or the PingAccess Admin UI in PingOne Advanced Services.

About this task

The API requires a JWT Bearer token for authenticating the requests. This token can be retrieved using user credentials or client credentials.

The API also includes interactive documentation for both developers and non-developers to explore the API endpoints, view documentation for the API, and experiment with API calls. You can make API calls from an interactive user interface, custom applications, or from command line tools such as cURL.

The Swagger UI component that displays the Self-Service admin API documentation uses OpenAPI specification (OAS) 3.1. Access to these specifications simplifies the process of integrating the Self-Service API with modern API clients, such as Postman.

Learn more in Accessing the API interactive documentation.

Accessing the API interactive documentation

To access the administrative API documentation:

  1. Start a web browser.

  2. Browse to the URL:

    https://self-service-api.<environment>-<customer>.<region>.ping.cloud/docs
    The API is also documented in the OpenAPI Specification, previously known as the Swagger Specification. Go to: 
    https://self-service-api.<environment>-<customer>.<region>.ping.cloud/api/v1/openapi.json

Authenticate using user credentials

To authenticate using user credentials, you’ll use the Swagger UI to generate an access token.

Before you begin

To access the API using user credentials, ensure that users are assigned the P1AS Self-Service role. To assign these roles, you must be a PingOne Identity Data Admin. To learn more, access the instructions in Assigning self-service roles.

Steps

  1. Navigate to the interactive documentation. You can find instructions in Accessing the interactive documentation.

  2. Click Get Token at the top of the page.

    A new tab opens and redirects you to the sign-on page.

  3. Enter your credentials and click Submit.

    If authentication is successful, you’re redirected to the Success page and a Copy Token button displays.

  4. Click Copy Token.

  5. From there, you can use the token in different ways. You can:

    • Use the Swagger UI.

      1. Click Authorize, which is next to Get Token.

      2. Paste the token in the input field, and Authorize, and then click Close. All API requests that come from Swagger UI will now be authenticated.

    • Query the API directly using other tools, such as Postman or cURL, and include the bearer token in the headers.

      Example
      {"Authorization": "Bearer {TOKEN}"}

Authenticate using client credentials

To authenticate using client credentials, create a client credentials application in your PingOne environment and then generate an access token.

To set this up, you’ll need to:

  • Create the client credentials application

  • Generate the token

You should also restrict access to this application to PingOne administrators. Learn more in Restricting access to the application.

In addition to the JWT Bearer token, the API uses role-based access control, as described in Administrative role mappings. The roles assigned to the accounts affect the results of the API calls.

Creating the client credentials application

Start by creating an OIDC application in PingOne.

Steps

  1. Go to Applications > Resources.

  2. Click the + icon.

  3. Create the resource by completing these fields:

    • Resource name: A unique identifier for the resource.

    • Description (optional): A brief characterization of the resource that helps identify it.

  4. Click Next.

  5. On the Attributes page, click Add to add a new attribute.

  6. Name the new attribute groups.

    Set the value to a hardcoded list of valid Self-Service roles. For example, {“dev-tls-admin”, “prod-tls-audit”}. You can find a complete list of these roles in Administrative role mappings.

    The Self-Service attribute must be set up for it to display in the list. You can find instructions on adding this attribute in Creating custom attributes.

  7. Click Next.

  8. On the Scopes page, add a new scope to map the Self-Service role to the new application. Click Add Scope and complete the following fields:

    • Scope name: A unique identifier for the scope.

    • Description (optional): A brief characterization of the scope that helps identify it.

  9. Click Save.

  10. Now, add the OIDC application. Go to Applications > Applications.

  11. Click the + icon.

  12. Complete the following fields:

    • Application name: A unique identifier for the application.

    • Description (optional): A brief characterization of the application that helps identify it.

    • Icon (optional): A graphic representation of the application. Use a file up to 1 MB in JPG, JPEG, GIF, or PNG format.

  13. In the list of available application types, select OIDC Web App. Click Save.

  14. On the Configuration tab, click the Pencil icon to edit the configuration.

    • Change the Response Type to none by clearing all the options.

    • Change the Grant Type to Client Credentials.

  15. Click Save.

  16. On the Resources tab, click the Pencil icon to add the scope you added in step 8 to the application.

  17. Click Save and click the toggle to enable the application.

Generating the token

Access the new application in the PingOne console to generate an access token.

Steps

  1. Follow the steps outlined in Getting an access token in the PingOne documentation.

  2. Include the bearer token in the headers.

    Example
    {"Authorization": "Bearer {TOKEN}"}

Restricting access to the application

To ensure that only administrators can generate access tokens, restrict access to it.

Steps

  1. Select the application, click the Access tab, and then the Pencil icon.

  2. Select the Admin Only Access checkbox and click Save.

Assigning Self-Service roles

Assign users the appropriate PingOne Advanced Services Self-Service roles on the Users page in the directory. To assign these roles, you must be assigned the PingOne Identity Data Admin role.

Steps

  1. Go to Directory > Users and browse or search for the users that you want to assign the role to.

  2. Click the user entry to open the user details panel, and then click the Pencil icon in the profile.

  3. On the bottom of the page, in the Custom Attributes list, select P1AS Self-Service Roles.

  4. Click Save.