|
| 1 | +# Ping Protect |
| 2 | + |
| 3 | +The Ping Protect module is intended to be used along with the ForgeRock JavaScript SDK to provide the Ping Protect feature. |
| 4 | + |
| 5 | +**IMPORTANT NOTE**: This module is not yet published. For the current published Ping Protect package please visit https://github.com/ForgeRock/forgerock-javascript-sdk/tree/develop/packages/ping-protect |
| 6 | + |
| 7 | +## Overall Design |
| 8 | + |
| 9 | +There are two components on the server side and two components on the client side to enable this feature. You'll need to have the following: |
| 10 | + |
| 11 | +1. PingOne Advanced Identity Cloud (aka PingOne AIC) platform or an up-to-date Ping Identity Access Management (aka PingAM) |
| 12 | +2. PingOne tenant with Protect enabled |
| 13 | +3. A Ping Protect Service configured in AIC or AM |
| 14 | +4. A journey/tree with the appropriate Protect Nodes |
| 15 | +5. A client application with the `@forgerock/javascript-sdk` and `@pingidentity/protect` modules installed |
| 16 | + |
| 17 | +## Quick Start for Client Application |
| 18 | + |
| 19 | +Install both modules and their latest versions: |
| 20 | + |
| 21 | +```sh |
| 22 | +npm install @forgerock/javascript-sdk @pingidentity/protect |
| 23 | +``` |
| 24 | + |
| 25 | +The `@pingidentity/protect` module has a `protect()` function that accepts configuration options and returns a set of methods for interacting with Protect. The two main responsibilities of the Ping Protect module are the initialization of the profiling and data collection and the completion and preparation of the collected data for the server. You can find these two methods on the API returned by `protect()`. |
| 26 | + |
| 27 | +- `start()` |
| 28 | +- `getData()` |
| 29 | + |
| 30 | +When calling `protect()`, you have many different options to configure what and how the data is collected. The most important and required of these settings is the `envId`. All other settings are optional. |
| 31 | + |
| 32 | +The `start` method can be called at application startup, or when you receive the `PingOneProtectInitializeCallback` callback from the server. We recommend you call `start` as soon as you can to collect as much data as possible for higher accuracy. |
| 33 | + |
| 34 | +```js |
| 35 | +import { protect } from '@pingidentity/protect'; |
| 36 | + |
| 37 | +// Call early in your application startup |
| 38 | +const protectAPI = await protect({ envId: '12345' }); |
| 39 | +await protectAPI.start(); |
| 40 | +``` |
| 41 | + |
| 42 | +Alternatively, you can delay the initialization until you receive the instruction from the server by way of the special callback: `PingOneProtectInitializeCallback`. To do this, you would call the `start` method when the callback is present in the journey. |
| 43 | + |
| 44 | +```js |
| 45 | +if (step.getCallbacksOfType('PingOneProtectInitializeCallback')) { |
| 46 | + try { |
| 47 | + // Asynchronous call |
| 48 | + await protectAPI.start(); |
| 49 | + } catch (err) { |
| 50 | + // handle error |
| 51 | + } |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +You then call the `FRAuth.next` method after initialization to move the user forward in the journey. |
| 56 | + |
| 57 | +```js |
| 58 | +FRAuth.next(step); |
| 59 | +``` |
| 60 | + |
| 61 | +At some point in the journey, and as late as possible in order to collect as much data as you can, you will come across the `PingOneProtectEvaluationCallback`. This is when you call the `getData` method to package what's been collected for the server to evaluate. |
| 62 | + |
| 63 | +```js |
| 64 | +let data; |
| 65 | + |
| 66 | +if (step.getCallbacksOfType('PingOneProtectEvaluationCallback')) { |
| 67 | + try { |
| 68 | + // Asynchronous call |
| 69 | + data = await protectAPI.getData(); |
| 70 | + } catch (err) { |
| 71 | + // handle error |
| 72 | + } |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +Now that we have the data, set it on the callback in order to send it to the server when we call `next`. |
| 77 | + |
| 78 | +```js |
| 79 | +callback.setData(data); |
| 80 | + |
| 81 | +FRAuth.next(step); |
| 82 | +``` |
| 83 | + |
| 84 | +## Error Handling |
| 85 | + |
| 86 | +When you encounter an error during initialization or evaluation, set the error message on the callback using the `setClientError` method. Setting the message on the callback is how it gets sent to the server on the `FRAuth.next` method call. |
| 87 | + |
| 88 | +```js |
| 89 | +if (step.getCallbacksOfType('PingOneProtectInitializeCallback')) { |
| 90 | + const callback = step.getCallbackOfType('PingOneProtectInitializeCallback'); |
| 91 | + try { |
| 92 | + // Asynchronous call |
| 93 | + await protectAPI.start(); |
| 94 | + } catch (err) { |
| 95 | + callback.setClientError(err.message); |
| 96 | + } |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +A similar process is used for the evaluation step. |
| 101 | + |
| 102 | +```js |
| 103 | +let data; |
| 104 | + |
| 105 | +if (step.getCallbacksOfType('PingOneProtectEvaluationCallback')) { |
| 106 | + const callback = step.getCallbackOfType('PingOneProtectEvaluationCallback'); |
| 107 | + try { |
| 108 | + // Asynchronous call |
| 109 | + data = await protectAPI.getData(); |
| 110 | + } catch (err) { |
| 111 | + callback.setClientError(err.message); |
| 112 | + } |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +## Full API |
| 117 | + |
| 118 | +```js |
| 119 | +// Protect methods |
| 120 | +start(); |
| 121 | +getData(); |
| 122 | +pauseBehavioralData(); |
| 123 | +resumeBehavioralData(); |
| 124 | +``` |
| 125 | + |
| 126 | +```js |
| 127 | +// PingOneProtectInitializeCallback methods |
| 128 | +callback.getConfig(); |
| 129 | +callback.setClientError(); |
| 130 | +``` |
| 131 | + |
| 132 | +```js |
| 133 | +// PingOneProtectEvaluationCallback methods |
| 134 | +callback.setData(); |
| 135 | +callback.setClientError(); |
| 136 | +callback.getPauseBehavioralData(); |
| 137 | +``` |
0 commit comments