Web Access Management

Configuring an IdP adapter instance

Configure the WAM Integration Kit for an identity provider (IdP).

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 IdP Adapter tab in the following procedure.

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

Steps

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

    Choose from:

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

    • For PingFederate 10.0 or earlier: go to Identity 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 IdP 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 IdP Adapter settings.

  3. (Only for custom plug-ins for WAM servers other than OAM or RSA) On the IdP Adapter 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. In the Action column, click Update.

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

      Skip the next step.

  4. (Only for the RSA bundled plug-in) On the IdP Adapter 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 have specified 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: The 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 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. (Only for custom plug-ins for WAM servers and the OAM bundled plug-in) On the IdP Adapter tab, click Add a new row to 'Authentication Context Mapping Table' and enter the following information:

    • Authentication Level: A specific value for a WAM system indicating the level of authentication an end-user has gone through.

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

    1. In the Action column, click Update. Repeat this step as needed.

  6. Provide entries on the IdP Adapter tab, as described on the tab and in the following table.

    The selected WAM Plug-in Type may override optional and required 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 the WAM Session Cookie as secure.

    If this option is enabled, the browser will send the WAM Session Cookie via 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 used.

    Authorization Error URL

    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 the WAM server and would simply 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.

    Login URL

    An optional URL for the authentication service. If the WAM session cookie is not found in the request, PingFederate redirects the request to the URL page along with the relative resumePath. This service must be protected by the WAM Agent.

    Per-Adapter SLO URL

    If a URL is entered into this field, it will be used as the redirect target during SLO for this adapter instance, instead of the default value from PingFederate.

    Authentication Context

    This may be any value agreed upon with your SP partner that indicates how the user was authenticated. The value is included in the SAML assertion. Standard URIs are defined in the SAML specifications. You can find more information in the Authentication Context for the OASIS Security Assertion Markup Language(SAML) V2.0 PDF on the OASIS site.

    Authentication Level Identifier

    Identifier used for the Authentication Level attribute.

    Repad Token String

    Enable this to pad the incoming session token (if required).
    A screenshot that shows the advanced WAM IdP Adapter settings.

  7. (Optional) Click Show Advanced Fields to specify OpenToken configuration values or settings, depending on your network configuration and other requirements at your site.

    This section also contains fields for configuring tokens capturing the original request information if necessary. This functionality is based on the ObFormLoginCookie from OAM.

    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 table below.
    Advanced Fields
    Field Description

    OpenToken Name

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

    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 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) for 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, the OpenToken cookie 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.

    Create Form Login Token

    If selected, a Token is created containing the information needed to retain the original request information if a redirect to a form authentication page is required.

    The token contents are implemented based on the requirements of the ObFormLoginCookie from OAM.

    Form Login Cookie Name

    The name given to the created Form Login Cookie

    For example, ObFormLoginCookie.

    Form Login Cookie Domain

    The server domain, preceded by a period.

    For example, .example.com.

    Form Login Cookie Path

    The path for the cookie that contains the Form Login Cookie.

    Form Login Cookie is Secure

    Sets the secure flag on the Form Login Cookie.

    Form Login Cookie is HTTP Only

    Sets the httpOnly flag on the Form Login Cookie.

    Form Login Token Transfer Method

    Specifies how the Form Login Token is transferred. Select one of the following options:

    • Through a cookie

    • As a query parameter

    Create Form Login Cookie for Host

    If selected, the Form Login Cookie is created for the hostname in the request, ignoring the Form Login Cookie Domain.

    RU URL

    Determines how the ru URL is derived:

    Base

    Full path using the RH from the PF BASE URL.

    Request

    Full path using the RH from the HTTP request.

    Relative

    Use relative (do not add RH).

    Reset Invalid Session Cookie

    If selected, the invalid session cookie is set to the configured logged-off value before redirecting to the Login URL.

  8. Click Next.

  9. On the Actions tab, click the Test Connection link 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 that you want to include in the contract. Click Next.

  11. On the Adapter Attributes tab, select userId or wamSessionToken under Pseudonym. You can also select any extended attributes specified on the previous screen. Click Next.

    Learn more in Set pseudonym and masking options in the PingFederate documentation. Click Next.

  12. 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 IdP Adapter Instances tab, click Save.