--- title: Launching a PingOne flow with a redirect description: You can configure PingOne and DaVinci so that you can invoke specifically-configured flows through PingOne. component: davinci page_id: davinci:integrating_flows_into_applications:davinci_launch_flow_redirect canonical_url: http://docs.pingidentity.com/davinci/integrating_flows_into_applications/davinci_launch_flow_redirect.html revdate: May 6, 2024 section_ids: configuring-a-davinci-flow-for-invocation: Configuring a DaVinci flow for invocation about-this-task: About this task steps: Steps using-pingone-connectors: Using PingOne connectors referencing-pingone-data-in-the-flow: Referencing PingOne data in the flow configuring-a-davinci-flow-policy-for-invocation: Configuring a DaVinci flow policy for invocation about-this-task-2: About this task steps-2: Steps configuring-pingone-for-flow-invocation: Configuring PingOne for flow invocation about-this-task-3: About this task steps-3: Steps choose-from: Choose from: invoking-the-flow: Invoking the flow steps-4: Steps --- # Launching a PingOne flow with a redirect You can configure PingOne and DaVinci so that you can invoke specifically-configured flows through PingOne. This approach lets you launch your flows from PingOne and lets you reference and modify user data from PingOne within the flow. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To switch between using a flow for a DaVinci widget integration and an integration using a PingOne redirect, see [Switching between PingOne and DaVinci widget integrations](davinci_switch_between_flow_integrations.html). | ## Configuring a DaVinci flow for invocation Update a DaVinci flow to enable it to be launched through PingOne. ### About this task This procedure assumes that the flow already exists or is in progress, and only specifies the necessary nodes and settings for invocation through PingOne. For more information about creating flows, see [Getting started with DaVinci](../flows/davinci_getting_started.html). ### Steps 1. Sign on to DaVinci and click the **Flows** tab. 2. Select the flow tile for the flow that you plan to launch through PingOne. 3. Click **More options ( [icon: ellipsis-v, set=fa]) > Flow Settings** to show the flow settings. 4. Select the **PingOne Flow** option. 5. Click **Save**, then close the **Flow Settings** pane. 6. End the flow with the following two **PingOne Authentication** nodes, one for success and one for failure. ![A screen capture of a flow ending with a success and failure path.](_images/kuw1674237257955.png) | Node | Purpose | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return a Success Response (Redirect Flows)** | This creates a PingOne session for the user and redirects the browser back to the source of the authentication request. This response provides the requested scopes as well as an access token, ID token, or SAML assertion. | | **Return an Error Response (Redirect Flows)** | This redirects the browser back to the source of the authentication request. This response provides information about the error that occurred. | 7. Click **Save**, then click **Deploy**. ## Using PingOne connectors Add PingOne connectors to your environment to use PingOne capabilities in your flows. Learn more about the available PingOne connectors in [Core connectors](../connectors/davinci_core_connectors.html). If you plan to launch flows through PingOne, you must add the PingOne Authentication connector to your environment. ## Referencing PingOne data in the flow You can reference data from PingOne within your flow. The format for this information is `global.parameters.`. Some parameters depend on the protocol used to launch the flow, while others are supplied by the PingOne application. OIDC parameters | Property | Description | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authorizationRequest` | An object that specifies all the parameters from the OIDC authorization request. | | `authorizationRequest.` | A string that specifies a custom URL parameter added to the OIDC authorization request. Replace *\* with the name of the custom URL parameter. | | `authorizationRequest.client_id` | A string that specifies the client ID of the application associated with this authorize request. | | `authorizationRequest.redirect_uri` | A string that specifies the URL of the return entry point of the application. | | `authorizationRequest.response_type` | A string that specifies the code or token type returned by an authorization request. Options are `token`, `id_token`, and `code`. | | `authorizationRequest.scope` | A string that specifies the permissions that determine the resources that the application can access. | | `authorizationRequest.state` | A string that maintains the state between the logout request and the callback to the endpoint specified by the `post_logout_redirect_uri` query parameter. | | `authorizationRequest.nonce` | A string that is used to associate a client session with a token to mitigate replay attacks. The value is passed through unmodified from the authentication request to the token. This is an optional property for authorization requests that return a code. | | `authorizationRequest.acr_values` | A string that is used by the flow designer to pass in useful information. | | `authorizationRequest.login_hint` | A string that is used to designate a login identifier to pre-fill the **username** field of the sign-on screen. | | `authorizationRequest.max_age` | A string that specifies the maximum amount of time allowed (in seconds) since the user last authenticated. If the `max_age` value is exceeded, the user must re-authenticate. If the `max_age` value is set to 0 (`max_age=0`), the user is always required to re-authenticate. | | `authorizationRequest.prompt` | A string that specifies whether the user is prompted to sign on for re-authentication. The prompt parameter can be used as a way to check for existing authentication, verifying that the user is still present for the current session. | | `authorizationRequest.response_mode` | A string that specifies the mechanism for returning authorization response parameters from the authorization endpoint. Options are `query`, `fragment`, and `form_post`. | | `authorizationRequest.code_challenge` | A string that is computed from the `code_verifier` that is used in a Proof Key for Code Exchange (PKCE) authorization request. | | `authorizationRequest.code_challenge_method` | A string that specifies the computation logic used to generate the `code_challenge` string. The token endpoint uses this method to verify the `code_verifier` for PKCE authorization requests. Options are `plain` and `S256`. | | `authorizationRequest.code_verifier` | A string that is used to create the `code_challenge` value passed to the authorization server in the request. | | `authorizationRequest.mobileRequest` | An object that specifies OIDC/OAuth2 request parameters. | For example, the following code references the login hint in a flow launched using OIDC: ```none global.parameters.authorizationRequest.login_hint ``` SAML parameters | Property | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `samlRequest` | A string that specifies all the parameters from the SAML request. | | `samlRequest.spEntityId` | A string that specifies the service provider entity ID used to look up the application. This is a required property and is unique within the environment. | | `samlRequest.forceAuthn` | A boolean that, when set to true, specifies that the identity provider must authenticate the presenter directly rather than rely on a previous security context. If a value is not provided, the default value is false. | | `samlRequest.passive` | A boolean that, when set to true, specifies that the identity provider and the user agent itself must not visibly take control of the user interface from the requester and interact with the presenter in a noticeable fashion. If a value is not provided, the default value is false. | | `samlRequest.signed` | A boolean that specifies whether the SAML assertion should be signed. The default value is false. | | `samlRequest.subject` | A string that specifies the SAML subject ID. | | `samlRequest.requestedAuthnContext` | A string that specifies the authentication methods for the request. | | `samlRequest.` | A string or array that contains the value or values of any HTTP request parameter included in the **Initiate Single Sign-On URL**, up to a maximum of 4096 characters.For example, if the **Initiate Single Sign-On URL** used was:`https://sso.example.ca/saml20/idp/startsso?spEntityId=SP&key1=valueA&key2=valueB&key2=valueC`The **samlRequest.key1** parameter would be a string with a value of `valueA`. The **samlRequest.key2** parameter would be an array with a value of `["valueB", "valueC"]`. | For example, the following code references the subject ID in a flow launched using SAML: ```none global.parameters.samlRequest.subject ``` WS-Federation parameters | Property | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `wsFedRequest.wfresh` | The maximum age of authentication in minutes. If the value is 0, the user should be prompted for authentication before a token is issued. | | `wsFedRequest.wauth` | The required authentication level. | | `wsFedRequest.wctx` | An opaque context value that can be passed in the request.When the invoked DaVinci flow completes successfully and returns to PingOne, PingOne echoes this value back to the service provider with the issued token if it was included by the service provider in the originating request. | | `wsFedRequest.whr` | The account partner realm of the client. | Application parameters | Property | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application` | An object that specifies the configuration information about the PingOne application that initiated the authentication request. | | `application.homePageUrl` | A string that specifies the custom home page URL for the application. | | `application.id` | A string that specifies the application ID. | | `application.name` | A string that specifies the application name. | | `application.protocol` | A string that specifies the protocol for the application. Options are OPENID\_CONNECT and SAML. | | `application.type` | A string that specifies the application type. Valid values are `WEB_APP`, `NATIVE_APP`, `SINGLE_PAGE_APP`, `SERVICE`, `CUSTOM_APP`, `WORKER`, `PING_ONE_SELF_SERVICE`, `PING_ONE_ADMIN_CONSOLE`, `PING_ONE_PORTAL`, `TEMPLATE_APP`, and `PORTAL_LINK_APP`. | For example, the following code references the application ID in a flow, regardless of the protocol used to launch the flow: ```none global.parameters.application.id ``` Universal parameters | Property | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `loginHint` | A string that specifies an identifier to pre-fill the **username** field of a sign-on screen. | | `maxSecondsSinceLastSignOn` | An integer that specifies the maximum amount of time allowed (in seconds) since the user last authenticated. If the user's last sign on in the session is greater than the integer value specified in this property, then existing session information cannot be used to skip authentication or influence any authentication logic. This value is set automatically to 0 if `prompt=login` is set for an OIDC application or if `ForceAuthn=true` is set for a SAML application. Otherwise, this value is set to the `max_age` property value for OIDC applications, if present, or omitted otherwise. | For example, the following code references the login hint, regardless of the protocol used to launch the flow: ```none global.parameters.loginHint ``` ## Configuring a DaVinci flow policy for invocation Configure a flow policy to specify which flow and which version of the flow you want to launch. ### About this task Flows in DaVinci flows often have multiple versions as administrators make changes, and not all of these versions should be presented to users. A flow policy ensures that users see the correct version of the correct flow. ### Steps 1. Sign on to DaVinci and click the **Applications** tab. 2. Find the application and click **Edit**. 3. Click the **Flow Policy** tab. 4. Click **Add Flow Policy**. 5. In the **Name** field, enter a name for the flow policy. 6. Select **PingOne Flow Policy**. 7. Add one or more PingOne flows to the policy. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PingOne flow policies can only include flows and flow versions that have the **PingOne Flow** setting enabled. Flows and versions without this setting cannot be selected. | 1. In the **Flows** section, select a flow. 2. In the **Version** section, select one or more versions of the flow. The **Latest Version** option always uses the latest version. 3. (Optional) Repeat the previous steps to add additional flows. 8. Click **Create Flow Policy**. The **Edit Your Weight Distribution** modal opens. 9. Add weight distribution and analytics information for each flow and flow version: 1. In the **Distribution** field for each flow version, enter or select a distribution weight from 1 to 100. | | | | - | ------------------------------------------------------------------------------------------------------------------ | | | The weight is used if the flow policy is invoked without a flow ID. You can use the weight to perform A/B testing. | 2. (Optional) Click **Add IP Whitelist**. 3. (Optional) In the **Whitelist IP** field, enter one or more IP addresses. | | | | - | ---------------------------------------------------------------------------------------------------------- | | | If a request comes from an allowed IP address, the weight is ignored, and the specified flow is triggered. | 4. (Optional) In the **Analytics - Select Success Nodes** list, select one or more nodes that, when run, indicate that the flow run was successful. This information is used to calculate the flow policy's success rate. 10. Click **Save Flow Policy**. ## Configuring PingOne for flow invocation Configure an application in PingOne to launch flows. ### About this task The properties of the PingOne application are used as part of the URL that launches the flow. ### Steps 1. Sign on to PingOne and go to **Applications > Applications**. 2. Click the **[icon: plus, set=fa]**icon. 3. In the **Application Name** field, enter a name for the application. 4. In the **Application Type** section, select **OIDC Web App** or **SAML Application**. 5. If you selected **SAML Application**, provide the SAML configuration. 1. Click **Configure**. 2. Select a method for providing the application metadata. #### Choose from: * **Import Metadata**: Import the configuration details from an XML metadata file. Click **Select a File** and then select an XML metadata file on your system. Click **Open**. If the metadata file does not specify all the configuration values, you must enter the missing values manually. * **Import From URL**: Import the configuration details from a metadata URL. Enter the URL and then click **Import**. The URL must be a valid absolute URL. * **Manually Enter**: Enter the configuration details manually. In the **ACS URLs** field, enter the Assertion Consumer Service (ACS) URLs. You must specify at least one URL, and the first URL in the list is used as the default. In the **Entity ID** field, enter the service provider entity ID used to look up the application. 6. Click **Save**. 7. Click the **Policies** tab. 8. Click **[icon: plus, set=fa]Add Policies**. 9. Click the **DaVinci Policies** tab. 10. Select one or more flow policies to add to the application. Only flow policies with the **PingOne Policy** option are displayed. 11. Click **Save**. 12. Click the **Configuration** tab. 13. Click the **Pencil** icon. 14. In the **CORS Settings** section, select **Allow specific origins**. 15. In the **Allowed Origins** field, enter the domain from which you plan to launch the flow. 16. Click **Save**. ## Invoking the flow To launch the flow, construct a link with the PingOne details and add it to the resource that will launch the flow. ### Steps 1. In the resource that will launch the flow, such as your organization's web application, add a call to your PingOne application using the following format: ``` https://auth.pingone.com//as/authorize?response_type= &client_id= &redirect_uri= &scope= &acr_values= &= ``` The following parameters are used in the call: **Table 1. Parameters** | Parameter | Required | Description | Location | | --------------------- | -------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Environment ID | Yes | The **Company ID** of the DaVinci application. | Available in DaVinci in the **Company** tab, or in the details section at the top of any flow or application. | | Response Type | Yes | The response type expected by the PingOne application. | Available in PingOne under **Applications > Applications**. Click your application, then click the **Configuration** tab and find the **Response Type** field. | | Client ID | Yes | The PingOne application's Client ID. | Available in PingOne under **Applications > Applications**. Click your application, then click the **Configuration** tab and find the **Client ID** field. | | Redirect URI | Yes | A redirect URI configured in PingOne. | Available in PingOne under **Applications > Applications**. Click your application, then click the **Configuration** tab and find the **Redirect URIs** field. | | Scope | Yes | The application request scope. | Available in PingOne under **Applications > Applications > Resources**. Click your application, then click the **Resources** tab and find the **Allowed Scopes** section. | | Flow Policy ID | No | A policy that determines which flow and version is run. | Available in DaVinci in the **Applications** tab. Select your application, then click the **Flow Policy** tab. | | Additional parameters | No | You can pass in additional parameters to make their values available during the flow. | N/A | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can reference the parameter values passed in with the invocation. The format is:``` global.parameters.authorizationRequest. ``` | 2. If the user requires a token but the flow did not grant a token, make an API call to the PingOne token endpoint to grant the user a token. Use the [PingOne token authentication code](https://apidocs.pingidentity.com/pingone/platform/v1/api/#post-token-authorization_code) endpoint or the [Pingone client credentials](https://apidocs.pingidentity.com/pingone/platform/v1/api/#post-token-admin-app-client_credentials) endpoint.