PingGateway 2024.9

PingOne as SAML IDP

This example shows how to use PingOne as the identity provider with unsigned/unencrypted assertions.

Before you start

  1. Add the following basic PingGateway configuration if you have not already done so:

    1. Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).

    2. Add the following route to PingGateway to serve the sample application .css and other static resources:

      • Linux

      • Windows

      $HOME/.openig/config/routes/00-static-resources.json
      %appdata%\OpenIG\config\routes\00-static-resources.json
      {
  "name" : "00-static-resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}",
  "handler": "ReverseProxyHandler"
}

  2. Set up the network:

    Add sp.example.com to your /etc/hosts file:

    127.0.0.1 localhost am.example.com ig.example.com app.example.com sp.example.com

    Traffic to the application is proxied through PingGateway, using the host name sp.example.com.

  3. Save the sp.xml file as the SAML service provider configuration file $HOME/.openig/SAML/sp.xml.

Prepare PingOne

  1. Prepare the PingOne environment and test user.

    Make sure you match the test user’s credentials to those known to the sample application.

  2. In the PingOne test environment, create a SAML web application with the following values:

    • Application Name: saml_app

    • Description: SAML application

    • Application Type: SAML Application

  3. In the application, select the Import Metadata panel, add the SAML configuration file sp.xml and save the application.

  4. On the Attribute Mappings panel, click edit (edit) and add the following mappings:

    saml_app PingOne

    cn

    Given Name

    sn

    Family Name

  5. On the Configuration panel, click edit (edit) and set the SLO BINDING’s SUBJECT NAMEID FORMAT to urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

  6. On the Configuration panel, click Download Metadata and save the downloaded file as the identity provider configuration file $HOME/.openig/SAML/idp.xml.

  7. On the Configuration panel, record the Initiate Single Sign-on URL.

    You need the value to set up PingGateway.

  8. At the top-right of the page, click the slider to enable the application.

Learn more from the PingOne documentation Add a SAML application.

Prepare PingGateway

  1. Copy the following example SAML configuration files to $HOME/.openig/SAML and edit them to match your configuration:

    File Required changes

    FederationConfig.properties

    None

    fedlet.cot

    Replace idp-entityID with the value of EntityDescriptor entityID in idp.xml.

    idp-extended.xml

    Replace idp-entityID with the value of EntityDescriptor entityID in idp.xml.

    sp-extended.xml

    None

  2. Make sure the PingGateway configuration at $HOME/.openig/SAML contains the following files:

    $ ls -l $HOME/.openig/SAML
FederationConfig.properties
fedlet.cot
idp-extended.xml
idp.xml
sp-extended.xml
sp.xml

  3. Add the following route to PingGateway:

    • Linux

    • Windows

    $HOME/.openig/config/routes/saml-filter.json
    %appdata%\OpenIG\config\routes\saml-filter.json
    {
  "name": "saml-filter",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "SamlFilter",
          "type": "SamlFederationFilter",
          "config": {
            "assertionMapping": {
              "name": "cn",
              "surname": "sn"
            },
            "subjectMapping": "sp-subject-name",
            "redirectURI": "/home/saml-filter"
          }
        },
        {
          "name": "SetSamlHeaders",
          "type": "HeaderFilter",
          "config": {
            "messageType": "REQUEST",
            "add": {
              "x-saml-cn": [ "${toString(session.name)}" ],
              "x-saml-sn": [ "${toString(session.surname)}" ]
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

  4. Restart PingGateway.

Validation

Test IDP-initiated login:

  1. In your browser’s privacy or incognito mode, go to the URL given by the web application property Initiate Single Sign-on URL.

    PingOne displays the sign-on page.

  2. Sign on to PingOne as the test user.

    PingGateway displays the sample application home page.

Test SP-initiated login:

  1. In your browser’s privacy or incognito mode, go to https://sp.example.com:8443/home.

  2. Sign on as the test user.

    The request is redirected to the sample application.

    PingGateway displays the sample application home page.

If a request returns an HTTP 414 URI Too Long error, read URI Too Long error.