From c61adc1fbe38541cfe6cfcdca9e794732d533aa0 Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Fri, 3 Nov 2023 13:00:03 -0700 Subject: [PATCH] chore: improve docs for hmac (#464) - update identity validation Co-authored-by: Muhsin Keloth --- .../live-chat/sdk/identity-validation.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/product/channels/live-chat/sdk/identity-validation.md b/docs/product/channels/live-chat/sdk/identity-validation.md index c1089ca6..38be123a 100644 --- a/docs/product/channels/live-chat/sdk/identity-validation.md +++ b/docs/product/channels/live-chat/sdk/identity-validation.md @@ -5,15 +5,15 @@ title: "Identity validation in Chatwoot" Identity verification is an important security feature that helps ensure that conversations between customers and support agents are private and secure. By verifying the identities of both parties, identity validation helps prevent impersonation and unauthorized access. -If your users can log into your app, it's always recommended to enable identify verification. Chatwoot uses a HMAC based identity verification. It is cryptographic algorithm that uses a secret key (provided by Chatwoot) and a unique identifier to generate a code, this code can then be used to verify the user on the frontend. +If your users can log into your app, it's always recommended to enable identity verification. Chatwoot uses an HMAC-based identity verification. It is a cryptographic algorithm that uses a secret key (provided by Chatwoot) and a unique identifier to generate a code; this code can then be used to verify the user on the front end. ## Generating HMAC -To generate the HMAC you need to first get the secret key for your Chatwoot inbox. The key can be found in `Settings > Inboxes > Settings > Configuration > Identity Validation` +To generate the HMAC you need to get the secret key for your Chatwoot inbox. The key can be found in `Settings > Inboxes > Settings > Configuration > Identity Validation` ![HMAC Secret](./images/hmac-secret.png) -To use HMAC for identity validation in your web widget, you'll need to generate an HMAC using this key. You can generate this HMAC using any programming language in the backend. Most languages have built in cryptographic functions to generate the token, if not popular implementations always exist. You can find examples of popular programming languages at the end of this page. +To use HMAC for identity validation in your web widget, you'll need to generate an HMAC using this key. You can generate this HMAC using any programming language in the backend. Most languages have built-in cryptographic functions to generate the token; if not popular implementations always exist. You can find examples of popular programming languages at the end of this page. ## Verifying the HMAC @@ -25,22 +25,22 @@ Once you've generated an HMAC for an identifier using the key above, you can use window.$chatwoot.setUser(``, { name: "", // Name of the user email: "", // Email of the user - identifier_hash: "" // Identifier Hash generated in the previous step + identifier_hash: "" // HMAC value, which is generated using inbox identifier (obtained from inbox settings ) and unique-identifier-key that you supply for the contact. } ``` -If the HMACs match, you can be confident that the person who sent the identifier is authorized to do so. All unverified users, will show up with alert mark, stating that the identity is not verified. +If the HMACs match, you can be confident that the person who sent the identifier is authorized to do so. All unverified users will show up with an alert mark stating that their identity is not verified. ![Unverified user](./images/unverified.png) ### Verification in React Native -You can integrate the identity verification in React Native as well. You can find the documentation to setup Chatwoot for React Native [here](/docs/product/channels/live-chat/integrations/react-native-widget) +You can integrate identity verification in React Native as well. You can find the documentation to setup Chatwoot for React Native [here](/docs/product/channels/live-chat/integrations/react-native-widget) ```jsx const App = () => { const user = { - identifier: "john@gmail.com", + identifier: "", name: "John Samuel", email: "john@gmail.com", identifier_hash: "", @@ -63,9 +63,9 @@ In case you want to enforce verification for all users, you can do so by enablin ![Enforce verification](./images/enforce-verification.png) -_If this option is enabled any incoming message from a unverified user will be rejected._ +_If this option is enabled any incoming message from an unverified user will be rejected._ -## Sample HMAC Generation for popular languagees +## Sample HMAC Generation for popular languages ### PHP @@ -74,10 +74,10 @@ _If this option is enabled any incoming message from a unverified user will be r // Define your key and message $key = 'your-secret-token-for-hmac'; -$message = 'some-unique-identifier'; +$identifier = 'unique-identifier-of-the-user'; // Generate the HMAC -$identifier_hash = hash_hmac('sha256', $message, $key); +$identifier_hash = hash_hmac('sha256', $identifier, $key); ?> ``` @@ -87,14 +87,14 @@ $identifier_hash = hash_hmac('sha256', $message, $key); ```js const crypto = require("crypto"); -// Define your key and message +// Define your key and identifier const key = "your-secret-token-for-hmac"; -const message = "some-unique-identifier"; +const identifier = "unique-identifier-key-of-the-user"; // Generate the HMAC const identifierHash = crypto .createHmac("sha256", key) - .update(message) + .update(identifier) .digest("hex"); ``` @@ -103,23 +103,23 @@ const identifierHash = crypto ```ruby require 'openssl' -# Define your key and message +# Define your key and identifier key = 'your-secret-token-for-hmac' -message = 'some-unique-identifier' +identifier = 'unique-identifier-of-the-user' # Generate the HMAC -identifier_hash = OpenSSL::HMAC.hexdigest('sha256', key, message) +identifier_hash = OpenSSL::HMAC.hexdigest('sha256', key, identifier) ``` ### Elixir ```elixir -# Define your key and message +# Define your key and identifier key = 'your-secret-token-for-hmac' -message = 'some-unique-identifier' +identifier = 'unique-identifier-of-the-user' # Generate the HMAC -signature = :crypto.hmac(:sha256, key, message) +signature = :crypto.hmac(:sha256, key, identifier) identifier_hash = Base.encode16(signature, case: :lower) ``` @@ -137,13 +137,13 @@ import ( ) func main() { - // Define your key and message + // Define your key and identifier key := []byte("your-secret-token-for-hmac") - message := []byte("some-unique-identifier") + identifier := []byte("unique-identifier-of-the-user") // Generate the HMAC hash := hmac.New(sha256.New, key) - hash.Write(message) + hash.Write(identifier) identifierHash := hex.EncodeToString(hash.Sum(nil)) // Print the HMAC @@ -158,11 +158,11 @@ func main() { import hashlib import hmac -# Define your key and message +# Define your key and identifier secret = bytes('your-secret-token-for-hmac', 'utf-8') -message = bytes('some-unique-identifier', 'utf-8') +identifier = bytes('unique-identifier-of-the-user', 'utf-8') # Generate the HMAC -hash = hmac.new(secret, message, hashlib.sha256) +hash = hmac.new(secret, identifier, hashlib.sha256) identifier_hash = hash.hexdigest() ```