Web Access Management

Configuring an SP adapter instance

Configure the WAM Integration Kit for a service provider (SP).

If you are using OAM, you can find configuration information in Creating a Custom Authentication Scheme for OAM.

Before you begin

You must create a third-party WAM Web Agent in your WAM tool before starting the following procedure. Several properties that you use to configure the agent are required to fill out the Instance Configuration tab in the following procedure.

You can find more details on configuring an agent in your WAM Server documentation.

Steps

  1. In the PingFederate administrative console, create a new SP adapter instance.

    Choose from:

    • For PingFederate 10.1 or later: go to Applications > Integration > SP Adapters. Click Create New Instance.

    • For PingFederate 10.0 or earlier: go to Service Provider > Adapters. Click Create New Instance.

  2. On the Type tab, set the basic adapter instance attributes:

    1. In the Instance Name field, enter a name for the adapter instance.

    2. In the Instance ID field, enter a unique identifier for the adapter instance.

    3. In the Type list, select WAM SP Adapter. Click Next.

      • If you are configuring the adapter for a custom plug-in (not bundled with this kit), continue to step 5.

      • If you are configuring the RSA AM Dispatcher server, continue with step 6.

      • If you are configuring OAM, continue at step 7.
      A screenshot that shows the WAM SP Adapter settings.

  3. (Only for custom plug-ins for WAM servers other than OAM or RSA) On the Instance Configuration tab, click Add a new row to 'WAM Server' and enter the following information:

    1. Enter the Hostname or the IP address where the WAM server is running.

    2. Specify the remaining WAM server values required for your configuration.

    3. Click Update in the Action column.

    4. Repeat this step as needed for additional WAM plug-ins.

      Skip the next step.

  4. (Only for the RSA bundled plug-in) On the Instance Configuration tab, click Add a new row to 'RSA AM Dispatcher Server' and enter the following information:

    You must specify at least one RSA AM Dispatcher Server.

    1. Enter the Hostname or the IP address and the (optional) Dispatcher Port where the RSA AM Dispatcher server is running.

      You must specify the authentication method used by the dispatcher server. If you specify multiple dispatcher servers, each server can have individual authentication methods.

    2. Specify the Authentication Type used by the RSA Dispatcher Server:

      • Clear: Clear text, no encryption.

      • Anon: Anonymous SSL, SSL encryption only.

      • Auth: Mutually authenticated SSL, SSL encryption with certificate-based encryption.

    3. If you select Auth as the Authentication Type, you must specify the following RSA server values:

      • Keystore Path: String filename of the private keystore file (PKCS12 only).

      • Keystore Password: The password for the private keystore.

      • Key Alias: The alias to your private key in the keystore.

      • Key Password: The private key password for the keystore.

    4. (Optional) Specify the Timeout value required for your configuration.

    5. In the Action column, click Update.

    6. Repeat this step as needed for additional RSA Servers.

  5. (Optional) Only for custom plug-ins for WAM servers and the OAM bundled plug-in) On the SP Adapter tab, click Add a new row to 'Protected Resource Mapping Table' and enter the following information:

    • Authentication Context: This is part of the SAML assertion.

    • Attribute Filter: The names and values of attributes that the assertion must contain for this protected resource.

    • Protected Resource: The protected resource to be accessed if the authentication context and attribute filters in the assertion match the provided values.

    Click Update in the Action column. Repeat this step as needed.

  6. Provide entries on the Instance Configuration tab, as described on the tab and in the table below.

    The selected WAM Plug-in Type might override optional andrequired fields.

    For example, if the selected WAM Plug-in Type is OAM, the Agent Config Location becomes a required field. Leaving this field blank generates an error message.
    Configuration Fields
    Field Description

    WAM Plug-in Type

    The class name for the specific WAM implementation.

    The WAM Plug-in Type determines optional and required fields.

    Agent Name

    This value must match the value used when the third-party WAM Web Agent was configured.

    Agent Secret

    This value must match the value used when the third-party WAM Web Agent was configured.

    Agent Config Location

    Required for OAM. This value must contain the full path to an XML network-configuration file generated by the access-management system.

    Failover

    The default is false, indicating load balancing is enabled and user-session states and configuration data are shared among multiple WAM servers.

    Select true to enable failover, indicating that when one server fails, the next server is used.

    Domain Name

    Enter the fully-qualified domain name for the Cookie Domain where the WAM session cookie is stored, preceded by a period.

    For example, .pingidentity.com

    Cookie Path

    (Required) The default value is the root directory (/). Specify a different path for the WAM session cookie location, if necessary.

    You can find more details in WAM Server documentation.

    Protected Resource

    (Required) The default value is all files in the root directory (/*). Specify a different path to the resources in the protected realm, if necessary.

    Error URL

    Enter a URL for redirecting the user if there are errors. For example, incorrect parameters in the link.

    This URL can contain query parameters. The URL has an errorMessage query parameter appended to it, which contains a brief description of the error that happened. The error page can optionally display this message on the screen to provide guidance on remedying the problem.

    When using the errorMessage query parameter in a custom error page, adhere to Web application security best practices to guard against common content injection vulnerabilities.

    If no URL is specified, the appropriate default error landing page appears. Learn more in Customizable user-facing pages in the PingFederate documentation.

    If you define an error redirect URL, errors are sent to the error URL and logged in the PingFederate server log, but not the PingFederate audit log.

    User Identifier

    (Required) Defines which attribute parsed from the WAM session cookie is the user identifier for use in the assertion.

    Session Token Name

    (Required) The WAM session cookie name.

    Session Token LOGGEDOFF Value

    (Required) The value representing a logged-out session token.

    HTTP Only

    Enable this option to set the WAM Session Cookie as HTTP Only.

    If this option is enabled, the browser will send the WAM Session Cookie through HTTP or HTTPS.

    Secure

    Enable this option to set WAM Session Cookie as secure.

    If this option is enabled, the browser sends the WAM Session Cookie through HTTPS only.

    PingFederate Base URL

    The base URL for PingFederate. If specified, this value is used for creating the return URL if the Cookie Provider URL is being used.

    Authorization Error URL

    The URL to redirect for authorization errors.

    Cookie Provider URL

    The URL for the cookie provider where PingFederate should redirect the request if the WAM session cookie is in a separate domain.

    This service must be protected by WAM and redirect back to the PingFederate resumePath.

    Cookie Provider Target Parameter

    The name of the parameter used to send the return URL for the cookie provider.

    Authentication Service URL

    The URL to which the user is redirected for an SSO event.

    This URL overrides the Target Resource, which is sent as a parameter to the Authentication Service.

    Authentication Scheme Secret

    (Required, except for RSA) The shared secret between the adapter and the custom authentication scheme deployed on the WAM server.

    Per-Adapter SLO URL

    Enter a URL to use as the redirect target during SLO for this adapter instance, instead of the default value from PingFederate.

    Account Link Service

    The URL for the Account Linking Service.

    This service must be protected by the WAM Web Agent and redirect back to the PingFederate resumePath.

    The local user id is obtained from the WAM session cookie.
    A screenshot that shows the advanced WAM SP Adapter settings.

  7. (Optional) Click Show Advanced Fields to configure how to send extended attributes or to specify OpenToken configuration values or settings.

    Learn more in Configuring an OpenToken SP Adapter instance in the PingFederate documentation.

    If you want to configure the use of OpenToken as part of the WAM adapter configuration, complete the fields as described on the IdP Adapter tab and in the following table.

    You can change default values or settings, depending on your network configuration and other requirements at your site.

    Advanced Fields
    Field Description

    Send Extended Attributes

    The method of sending extended attributes. These attributes can be sent along with the request through browser cookies, query parameters, or as an encrypted token.

    Learn more about defining the attributes on the Extended Contract tab in step 10.

    OpenToken Transfer Method

    Specifies how the OpenToken is transferred. Select one of the following options:

    • Through a cookie

    • As a query parameter

    • Through Form Post

    OpenToken Name

    The name of the cookie or request attribute that contains the OpenToken. This name should be unique for each adapter instance.

    OpenToken Password

    The password used for encrypting extended attributes.

    This password is also used to generate the configuration file that the OpenToken agent uses. You must configure a value for the OpenToken Password even if the OpenToken Cipher Suite is set to NULL.

    OpenToken Cipher Suite

    The algorithm, cipher mode, and key size to use for token encryption.

    OpenToken Cookie Domain

    The server domain, preceded by a period.

    For example, .example.com.

    If you don’t specify a domain, the value is obtained from the request.

    OpenToken Cookie Path

    The path for the cookie that contains the OpenToken.

    OpenToken Token Lifetime

    The duration (in seconds) during which the OpenToken is valid. Range is 1 - 28800.

    OpenToken Session Lifetime

    The duration (in seconds) during which the OpenToken can be re-issued without authentication. Range is 1 - 259200.

    Not Before Tolerance

    The amount of time (in seconds) to allow for clock skew between servers. Range is 0 - 3600.

    Session Cookie

    If selected, OpenToken is set as a session cookie (rather than a persistent cookie).

    Applies only if the OpenToken Transfer Method is set as Cookie.

    Secure Cookie

    If selected, the OpenToken cookie is set only if the request is on a secure channel (https).

    Applies only if the OpenToken Transfer Method is set as 'Cookie'.

    Set WAM Cookie

    If cleared, the WAM Cookie isn’t set in the browser.

    Add WAM Token

    If selected, adds the WAM session token to extended attributes in OpenToken.

    You can only use this flag if you’re sending extended attributes through OpenToken.

    Encode Token

    Select this checkbox to URL encode the token string if the WAM provider requires it.

    Idle Timeout

    The idle timeout (in seconds). This value can be used by the specific plugin while creating the session if required.

    Max Timeout

    The max timeout (in seconds). This value can be used by the specific plugin while creating the session.

  8. Click Next.

  9. On the Actions tab, click Test Connection to validate the WAM configuration.

    If you’re using an OpenToken Adapter Configuration, click the Invoke Download link and then click Export to download the agent-config.txt properties to a directory that the WAM Web Agent can read.

  10. On the Extended Contract tab, add any attributes you want to include in the request header. Click Next.

  11. On the Summary tab, check and save your configuration.

    Choose from:

    • For PingFederate 10.1 or later: click Save.

    • For PingFederate 10.0 or earlier: click Done. On the Manage SP Adapter Instances tab, click Save.