--- title: Configuring request parameters and SSO URLs description: On the OpenID Provider Info tab of the Protocol Settings window, you can define request parameters under Request Parameters. component: pingfederate version: 13.0 page_id: pingfederate:administrators_reference_guide:pf_config_request_parameter_sso_url canonical_url: https://docs.pingidentity.com/pingfederate/13.0/administrators_reference_guide/pf_config_request_parameter_sso_url.html revdate: June 11, 2024 section_ids: about-this-task: About this task steps: Steps example: Example --- # Configuring request parameters and SSO URLs On the **OpenID Provider Info** tab of the **Protocol Settings** window, you can define request parameters under **Request Parameters**. ## About this task You can define request parameters for the following purposes: * Allow custom request parameters to be include in the authentication requests to support OpenID provider (OP)-specific use cases. * Define the default values for the request parameters. * Specify whether the default values, if any, can be overridden at runtime. * Allow the target application to request different scopes at runtime. The OP can reject the requested scopes based on its client configuration. * Protect the requested authentication request, `acr_values`, the authentication requirement, `prompt`, or both so that none of them can be overridden at runtime by the application endpoint parameters - `RequestedAuthnCtx`, `IsPassive`, and `ForceAuthn`. Direct mapping is available for types of parameters with a contract or text value: * Client ID * Client IP * Extended properties * SP Connection Entity ID * OAuth scopes * Tracked HTTP parameters Use the No Mapping parameter type to capture "no default value". You can use the following types of parameters in expressions: * Signed request object claims * Chained attributes * SAML authentication request * HTTP Request ## Steps 1. Enter the request parameter's **Name**. 2. Select the request parameter's **Type** * **Context** * **Expression** * **Extended Properties** * **No Mapping** * **Text** * **Tracked HTTP Parameters** 3. Enter the request parameter's default **Value**. If you selected the **Context** type, the following are available for direct mapping: * **Client ID** * **Client IP** * **OAuth scopes** * **SP Connection Entity ID** * **SRI** This is optional if the target application is allowed to override the parameter value at runtime. When no default value is specified, any value provided by the target application is accepted by the `/sp/startSSO.ping` service provider (SP) application endpoint and the authentication endpoint. If the target application does not provide the parameter in its single sign-on (SSO) URL and no default value is specified, the parameter is not included in the authentication requests. This is required if the target application is not allowed to override the parameter value at runtime. When specified, the request parameter is always included in the authentication requests. If the target application is not allowed to override the parameter value at runtime, the default value is sent. 4. (Optional) To let the target application override the request parameter's default value during runtime, select the **Application Endpoint Override** checkbox. When this checkbox is selected, during runtime: * If the target application provides the parameter in its SSO URL to the `/sp/startSSO.ping` SP application endpoint or the authentication endpoint, the value in the SSO URL is used. * If the target application does not provide the parameter in its SSO URL, the default value is used. However, if the parameter doesn't have a default value, then the parameter is not included in authentication requests. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `/sp/init_login.ping` SP endpoint does not accept overridden values. The `login_hint` parameter is the only exception. The default value, if any, is used. See the note at the end of this topic for more information. | 5. Click **Add**. ## Example Consider the following examples of request parameters: ![Screenshot of Request Parameters](_images/hza1638492006560.png) * The `hd` parameter is defined with a default value that cannot be overridden at runtime. The parameter is always included in the authentication requests and the value is always `example.org`. * The `customMultiValued` parameter is defined with two default values that cannot be overridden at runtime. This multivalued parameter is always included in the authentication requests. The values are always as defined. * The `customOverridableOne` parameter is defined with a default value that can be overridden at runtime. This parameter is always included in the authentication requests. If the target application provides the parameter in its SSO URL, the value in the SSO URL is used. If the target application does not provide the parameter in its SSO URL, the default value is used. * To override the value, configure the target application to append the request parameter and the desired value to the **SSO Application Endpoint**, as shown on the **Summary & Activation** tab, as in the following example. https\://sso.example.com/sp/startSSO.ping?PartnerIdpId=https%3A%2F%2Fsso.alpha.local%3A9031 and **customOverridableOne=foo** * To construct a multivalued request parameter, append the request parameter multiple times with different values, as in the following example. https\://sso.example.com/sp/startSSO.ping?PartnerIdpId=https%3A%2F%2Fsso.alpha.local%3A9031 and `customOverridableOne=foo` and `customOverridableOne=bar` https%3A%2F%2Fsso.alpha.local%3A9031 is the URL-encoded value of `https://sso.alpha.local:9031`, the issuer value of the OP. * The `customOverridableTwo` parameter is defined without a default value. Parameters without default values require the **No Mapping** parameter type. Any value provided by the target application in the SSO URL is accepted. To include this parameter in the authentication requests to the OP, configure the target application to append the request parameter and the desired value to the **SSO Application Endpoint**. * To construct a multivalued request parameter, append the parameter multiple times with different values. If the target application does not provide the parameter in its SSO URL, the parameter is not included in the authentication requests. * The `scope` (standard) parameter is defined with a value matching that of the **Scopes** field, on the same tab, and with the option to allow the target application to override the value at runtime. In essence, the target application is allowed to dynamically change the scope it requires at runtime by appending the `scope` parameter and the desired scopes to the **SSO Application Endpoint**. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | While the target application can request different scopes, the OP can reject the requested scopes based on its client configuration. Work with the OP to understand which scopes are applicable to your use case to prevent runtime errors. | * The `acr_values` (standard) parameter is defined with a default value that cannot be overridden at runtime. As a result, the `RequestedAuthnCtx` parameter, if supplied in the SSO URL by the target application, is ignored. In the authentication requests, the value of the `acr_values` parameter is always set to the default value specified in the configuration. Define the `acr_values` parameter if you want to protect the requested authentication context from the target application. * The `prompt` (standard) parameter is defined with a default value of `login` that cannot be overridden at runtime. As a result, the target application will not be able to suppress the reauthentication requirement by including `IsPassive=true` in the SSO URL. In the authentication requests, the value of the `prompt` parameter is always set to `login`. If the `prompt` parameter is defined with a default value of `none` that cannot be overridden at runtime, the target application will not be able to request the end users to reauthenticate by including `ForceAuthn=true` in the SSO URL. In the authentication requests, the value of the `prompt` parameter is always set to `none`. If the `prompt` parameter is defined with a default value of `create` that cannot be overridden at runtime, PingFederate tells the target application to direct the user into the account creation flow rather than the login flow. The `create` value can't be combined with any other `prompt` values. * The `issuerSignedRequestClaim` parameter uses an OGNL expression to extract the `iss` claim from an incoming signed request. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | These examples use the `/sp/startSSO.ping` SP application endpoint. You can also use the `/sp/init_login.ping` SP protocol endpoint to invoke the Third Party Initiated Login flow. For more information, see [View SP protocol endpoints](help_sp_protocol_endpoints.html). | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For information about URL encoding, see third-party resources, such as [HTML URL-encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp). |