From 012b7d3ab48844e2bb06828b29b4668e759a8921 Mon Sep 17 00:00:00 2001 From: Johan Brissmyr Date: Fri, 1 Apr 2022 06:16:41 -0700 Subject: [PATCH 1/3] Reflect changes in segmentio/analytics.js-integrations/pull/671 --- .../destinations/catalog/castle/index.md | 204 ++++-------------- 1 file changed, 46 insertions(+), 158 deletions(-) diff --git a/src/connections/destinations/catalog/castle/index.md b/src/connections/destinations/catalog/castle/index.md index f4a389a648..6def43211d 100644 --- a/src/connections/destinations/catalog/castle/index.md +++ b/src/connections/destinations/catalog/castle/index.md @@ -2,200 +2,88 @@ title: Castle Destination id: 56a8f566e954a874ca44d3b0 --- -Once you enable the Castle integration, the [Castle JavaScript snippet](https://docs.castle.io/docs/sdk-browser) is placed on your website, and user data starts appearing in the Castle dashboard. -Client-side tracking works out of the box, however **your existing server-side calls need to be extended** with data from the incoming request. -Castle supports calling `identify`, `page`, `screen`, and `group`. Castle does *not* support the `alias` call. +[Castle](https://castle.io/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners) monitors every step of the customer journey to help visualize and proactively block fraud that would otherwise fly under the radar. Types of fraud or abuse that can be managed include bots, fake accounts, multi-accounting, and account sharing. -## Integration steps -1. Track successful and failed logins -1. Extend server-side tracking with request properties -1. `identify`, preferably on the server-side -1. _Optional:_ Use Castle's `authenticate` API to request a risk score -1. _Recommended:_ Secure Mode +This destination is maintained by Castle. -## Tracking successful and failed logins -A baseline integration of Castle includes tracking [successful and failed login attempts](https://docs.castle.io/docs/failed-logins). If you track these events using a Segment integration, you can use [Event Mapping](https://dashboard.castle.io/settings/events) to indicate which events correspond to Castle reserved events. +## Getting Started -> info "" -> If you request a Castle risk score for the "Logged in" event, you should **not** map that event to Castle's reserved `$login.succeeded`. Instead, [`authenticate`](https://docs.castle.io/docs/authentication-method) that event through Castle. See next section on _Requesting a risk score_. +1. From the Segment web app, click **Catalog**. +2. Search for "Castle" in the Catalog, select it, and choose which of your sources to connect the destination to. +3. Enter the "Publishable Key" into your Segment Settings UI which you can find in your property in the [Castle dashboard](https://dashboard.castle.io). +4. Calls will now be visible in Castle dashboards in real-time. -Here are two Ruby examples on how to track successful and failed login attempts (`context` and `integration` have been omitted for brevity): +**NOTE**: Castle will only ingest Segment *client-side* events at this point. Server-side events will be dropped and not processed. -```ruby -analytics.track( - user_id: '019mr8mf4r', - event: 'Logged in' -) -``` - -When you track failed logins, you can protect against account threats such as password guessing. If you don't know which user that generated the failed login, omit the `user_id`. Instead, whenever you have access to the user-submitted email field, add this to the event properties as `email` or `username` depending on how you identify your users. Sending both `user_id` and `email` at the same time does not cause any data problems. - -```ruby -# known user -analytics.track( - user_id: '019mr8mf4r', - event: 'Failed to log in' -) -# unknown user -analytics.track( - anonymous_id: UUID.generate, - event: 'Failed to log in', - properties: { - email: 'johan@example.com' - } -) -``` - -> info "" -> Segment requires either `user_id` or `anonymous_id` for the request to be processed. If you don't know which user generated the failed login create a UUID and provide it as `anonymous_id` - -## Extending server-side tracking with request properties -Tracking events from your server-side is crucial to prevent requests from getting blocked by malicious actors. This is recommended for all [Castle's reserved events](https://docs.castle.io/docs/events), such as logins and password changes. +**NOTE**: Castle only supports web integrations via Segment, but we are working on mobile support so please stay tuned. -> warning "" -> Server-side `track` events are dropped by Castle unless they contain the properties listed below. `identify` calls still create or update a user, but don't create a device if these properties are missing: -> - `context.ip`. The user's IP address, i.e. not your server's internal IP -> - `context.user_agent`, alternatively `context.headers` containing at least the `user_agent` field. -> - `context.client_id`. The _Client ID_ forwarded by the web or mobile SDK. - -These properties are described in detail in the next section. +--- -If you aren't tracking the properties above, you can still make the event appear in the user timeline by configuring it to _Force Track_ in the [Castle dashboard](https://dashboard.castle.io/settings/events). However, it does not attach to a device or contribute to the risk score. +## Page -Here's a Ruby example of a server-side `track` call extended with request properties: +If you're not familiar with the Segment Specs, take a look to understand what the [`page` method](https://segment.com/docs/connections/spec/page/) does. An example call would look like: -```ruby -analytics.track( - user_id: '019mr8mf4r', - event: 'Logged in' - context: { - ip: '8.8.8.8', - user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36', - client_id: '7a31b5a1-7e01-4377-b086-5a488ec8a0ca', - headers: { - accept_language: 'da, en-gb;q=0.8, en;q=0.7', - ... - } - }) +``` +analytics.page() ``` -> **Note:** If you're concerned about sending `client_id` and `headers` to all of your active Segment integrations, instead include them in the `integrations.Castle` object to keep them private to your Castle integration. - -### The `client_id` property -By forwarding a client identifier from the client-side to the server-side, you can link activity from the two sources to form a strong protection against attacks where this link is not present. - -The Castle JavaScript SDK (loaded by Analytics.js) forwards the client identifier as a browser cookie named `__cid`. +`page` calls will be sent to Castle as `$page` events. -The Castle [iOS](https://docs.castle.io/docs/sdk-ios) and [Android](https://docs.castle.io/docs/sdk-android) SDKs forward it as the HTTP header `X-Castle-Client-Id`. See the respective documentation pages for instructions on how to configure the header forwarding. + -```java -// com.segment.analytics.internal.Utils -String uuid = Utils.getDeviceId(); -OkHttpClient client = new OkHttpClient(); -Request request = new Request.Builder() - .url("https://api.yoursite.com/login") - .header("X-Castle-Client-Id", uuid) - .build(); -``` - -> **Note**: If you have a client-less integration, for instance if you're using Castle to protect a customer-facing API, set `client_id` to `false`. +## Track -### The `headers` property -By forwarding HTTP request headers from the server-side, Castle is able to build a richer device fingerprint and prevent malicious actors from spoofing the client environment. -For privacy reasons, **you do not want to send the "Cookie" header to Castle**, so make sure you delete if from the list of headers. +If you're not familiar with the Segment Specs, take a look to understand what the [Track method](https://segment.com/docs/connections/spec/track/) does. An example call would look like: ``` -{ - user_agent: 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.5) Gecko/20091102 Firefox/3.5.5 (.NET CLR 3.5.30729)', - accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8', - accept_language: 'en-us,en;q=0.5', - accept_encoding: 'gzip,deflate', - accept_charset: 'ISO-8859-1,utf-8;q=0.7,*;q=0.7' -} +analytics.track('Added to Cart') ``` -There are example implementations on how to extract request headers in [PHP](https://github.com/castle/castle-php/blob/e93de1532ef28af17b8bf2bef350e6995a580085/lib/Castle/Request.php#L31), [Ruby](https://github.com/castle/castle-ruby), and [Java](https://github.com/castle/castle-java/blob/96cdc7469aa0995a836100c3dfd370b10f299e8c/src/main/java/io/castle/client/objects/UserInfoHeader.java#L148). +`track` calls will be sent to Castle as a `$custom` events. -## Identify -When you call [`identify`](/docs/connections/spec/identify), a user will be created in Castle. The Segment special traits `email`, `username`, `name`, `createdAt`, `phone`, and `address` are mapped to Castle's reserved user traits. +--- -Any additional traits will be stored on the Castle user model as _custom traits_. +## Secure Mode -> **Recommended:** Prevent `identify` from getting blocked in the client during an account takeover by calling `identify` from your server. +In order to prevent user information from being spoofed by a bad actor, it is highly recommended to send the user information as a signed JWT when Castle.js is used in production. -Here's a complete JavaScript example of an `identify` call: +From your backend code, you need to encode the user as a JWT and sign it using your Castle "API Secret". Then, when Castle receives the JWT, the integrity of the user data will be verified to ensure that the data isn't being tampered with. -```javascript -analytics.identify('1234', { - email: 'johan@example.com', // recommended - createdAt: '2015-02-23T22:28:55.387Z', // recommended - name: 'Johan Brissmyr', // for display - username: 'brissmyr', // for display - balance: 1350, // custom trait - phone: '+1 415 254 9225', // improved risk scoring - address: { // improved risk scoring - street: '60 Rausch St', - city: 'San Francisco', - state: 'CA', - postalCode: '94103', - country: 'USA' - } -}); -``` +Below is an example of how to generate a JWT on your backend using the Ruby language: -> **Note:** If you call `authenticate` to obtain a risk score, you do *not* need to call `identify` from the server-side. Instead, `authenticate` provides a way to attach `traits` in the same call. +```ruby +jwt_from_backend = JWT.encode({ + id: '97980cfea0067', + email: 'peter@example.com' +}, ENV.fetch('CASTLE_API_SECRET'), 'HS256') +``` -## Secure Mode -Enable Secure Mode to prevent fraudsters from impersonating your users. +You then need to transfer the `user_jwt` object to your frontend either via a separate API call, or by injecting the code using a templating language: -> **Note:** Secure Mode is highly encouraged for production deployments, but can wait until after a completed proof a concept. -To enable Secure Mode in Analytics.js, you pass in the `secure` variable by rendering it in your server-side templates. The `secure` field should be a SHA256 hash of your Castle API Secret and the user ID. +```javascript +var userJwt = "<%= jwt_from_backend %>"; -Here's an JavaScript example of an `identify` call with Secure Mode being rendered with Ruby server-side templating language: +// Then use the `userJwt` argument instead of `user` when using any of the tracking methods +Castle.page({userJwt: userJwt}); -```javascript -analytics.identify('1234', { - email: 'johan@example.com', - createdAt: '2015-02-23T22:28:55.387Z', +analytics.identify('97980cfea0067', { + email: 'peter@example.com', }, { - integrations: { - Castle: { - secure: '<%%= OpenSSL::HMAC.hexdigest("sha256", "YOUR_CASTLE_API_SECRET", current_user.id.to_s) %>' - } + Castle: { + userJwt: userJwt } }); ``` -To use secure mode in your mobile app, you will need to first fetch the secure token from your server-side, for example: - -```ruby -# GET https://api.yoursite.com/token -def user_token(user_id) - OpenSSL::HMAC.hexdigest("sha256", "YOUR_CASTLE_API_SECRET", user_id.to_s) -end -``` - -## Requesting a risk score -Castle's adaptive authentication tells you whether to allow access, initiate a second factor of authentication, or log out the user. - -Since all Segment calls are called asynchronously, you'll need to use Castle's native SDKs to perform [adaptive authentication](https://docs.castle.io/docs/authentication-method). +When Castle receives a JWT version of the user object, its contents will override the user object sent the standard Segment way. From 3ec02968ea911b3f081d8b0d629e1b315936cb23 Mon Sep 17 00:00:00 2001 From: Johan Brissmyr Date: Fri, 1 Apr 2022 06:21:49 -0700 Subject: [PATCH 2/3] Remove comment --- src/connections/destinations/catalog/castle/index.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/connections/destinations/catalog/castle/index.md b/src/connections/destinations/catalog/castle/index.md index 6def43211d..4df3cb821a 100644 --- a/src/connections/destinations/catalog/castle/index.md +++ b/src/connections/destinations/catalog/castle/index.md @@ -30,18 +30,6 @@ analytics.page() `page` calls will be sent to Castle as `$page` events. - - ## Track If you're not familiar with the Segment Specs, take a look to understand what the [Track method](https://segment.com/docs/connections/spec/track/) does. An example call would look like: From 1837a56aca7bb9b6e50417249f79613c1663b944 Mon Sep 17 00:00:00 2001 From: forstisabella <92472883+forstisabella@users.noreply.github.com> Date: Mon, 4 Apr 2022 09:31:43 -0400 Subject: [PATCH 3/3] Apply suggestions from code review --- .../destinations/catalog/castle/index.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/src/connections/destinations/catalog/castle/index.md b/src/connections/destinations/catalog/castle/index.md index 4df3cb821a..6284acb489 100644 --- a/src/connections/destinations/catalog/castle/index.md +++ b/src/connections/destinations/catalog/castle/index.md @@ -3,26 +3,29 @@ title: Castle Destination id: 56a8f566e954a874ca44d3b0 --- -[Castle](https://castle.io/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners) monitors every step of the customer journey to help visualize and proactively block fraud that would otherwise fly under the radar. Types of fraud or abuse that can be managed include bots, fake accounts, multi-accounting, and account sharing. +[Castle](https://castle.io/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners){:target="_blank"} monitors every step of the customer journey to help visualize and proactively block fraud that would otherwise fly under the radar. Types of fraud or abuse that can be managed include bots, fake accounts, multi-accounting, and account sharing. This destination is maintained by Castle. +> note " " +> Castle only supports web integrations via Segment, but we are working on mobile support so please stay tuned. + ## Getting Started 1. From the Segment web app, click **Catalog**. 2. Search for "Castle" in the Catalog, select it, and choose which of your sources to connect the destination to. -3. Enter the "Publishable Key" into your Segment Settings UI which you can find in your property in the [Castle dashboard](https://dashboard.castle.io). +3. Enter the "Publishable Key" into your Segment Settings UI which you can find in your property in the [Castle dashboard](https://dashboard.castle.io){:target="_blank"}. 4. Calls will now be visible in Castle dashboards in real-time. -**NOTE**: Castle will only ingest Segment *client-side* events at this point. Server-side events will be dropped and not processed. +> note " " +> Castle will only ingest Segment *client-side* events at this point. Server-side events will be dropped and not processed. -**NOTE**: Castle only supports web integrations via Segment, but we are working on mobile support so please stay tuned. --- ## Page -If you're not familiar with the Segment Specs, take a look to understand what the [`page` method](https://segment.com/docs/connections/spec/page/) does. An example call would look like: +If you're not familiar with the Segment Specs, take a look to understand what the [`page` call](https://segment.com/docs/connections/spec/page/) does. An example call would look like: ``` analytics.page() @@ -32,13 +35,13 @@ analytics.page() ## Track -If you're not familiar with the Segment Specs, take a look to understand what the [Track method](https://segment.com/docs/connections/spec/track/) does. An example call would look like: +If you're not familiar with the Segment Specs, take a look to understand what the [`track` call](https://segment.com/docs/connections/spec/track/) does. An example call would look like: ``` analytics.track('Added to Cart') ``` -`track` calls will be sent to Castle as a `$custom` events. +`track` calls will be sent to Castle as `$custom` events. --- @@ -48,7 +51,7 @@ In order to prevent user information from being spoofed by a bad actor, it is hi From your backend code, you need to encode the user as a JWT and sign it using your Castle "API Secret". Then, when Castle receives the JWT, the integrity of the user data will be verified to ensure that the data isn't being tampered with. -Below is an example of how to generate a JWT on your backend using the Ruby language: +Below is an example of how to generate a JWT on your backend using Ruby: ```ruby jwt_from_backend = JWT.encode({