From b8cb7f987fd7f9bfca20cbbec1ab2ea3b8ecb100 Mon Sep 17 00:00:00 2001 From: nithinsas <129459714+nithinsas@users.noreply.github.com> Date: Mon, 25 Sep 2023 18:54:02 -0500 Subject: [PATCH] Update readme.md Added detailed Implementation steps for Captcha Integration --- policies/captcha-integration/readme.md | 97 +++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/policies/captcha-integration/readme.md b/policies/captcha-integration/readme.md index 7216f953..70333ff0 100644 --- a/policies/captcha-integration/readme.md +++ b/policies/captcha-integration/readme.md @@ -18,4 +18,99 @@ The Captcha response is inserted into a hidden field which the `SelfAsserted-Loc A [live version of this policy](https://b2cprod.b2clogin.com/b2cprod.onmicrosoft.com/oauth2/v2.0/authorize?p=B2C_1A_Captcha_signin&client_id=51d907f8-db14-4460-a1fd-27eaeb2a74da&nonce=defaultNonce&redirect_uri=https://jwt.ms&scope=openid&response_type=id_token&prompt=login) is available to test. ## Notes -This sample policy is based on [SocialAndLocalAccounts starter pack](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/tree/master/SocialAndLocalAccounts). All changes are marked with **Sample:** comment inside the policy XML files. Make the necessary changes in the **Sample action required** sections. \ No newline at end of file +This sample policy is based on [SocialAndLocalAccounts starter pack](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/tree/master/SocialAndLocalAccounts). All changes are marked with **Sample:** comment inside the policy XML files. Make the necessary changes in the **Sample action required** sections. + +## Implementation notes: + +In this proof-of-concept implementation, Google reCAPTCHA v2 checkbox is being used. + +The links below provide more information about Google reCAPTCHA versions: +[reCAPTCHA Developer's Guide](https://developers.google.com/recaptcha/intro) +[reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) + +Additionally, a “Captcha Handler API” needs to be built to help to handle the captcha integration. A sample API solution can be found in [policies/captcha-integration/Captcha-Handler-API](https://github.com/azure-ad-b2c/samples/tree/master/policies/captcha-integration/Captcha-Handler-API) + +For proof of concept, instead of building an independent API solution, an Azure Function API can be substituted as handler. Azure Function API code can be found in [policies/captcha-integration/Captcha-Handler-API-AzFunc/run.csx](https://github.com/azure-ad-b2c/samples/blob/master/policies/captcha-integration/Captcha-Handler-API-AzFunc/run.csx) + +Detailed steps to create a Captcha Handler API with Azure Function App are also mentioned below. + +### How does reCAPTCHA token verification work? + +1, The client (application) presents a “verification request” aka reCAPTCHA token request to the Google reCAPTCHA services. This is normally presented as a challenge. + +2, Google reCAPTCHA services responds by providing a captcha token. + +3, The client application form submits a request along with the captcha token to the “Captcha handler API” endpoint (Eg: Azure Function API endpoint). + +4, The handler API sends a request to verify reCAPTCHA token to Google reCAPTCHA services. + +5, Google will provide a verification result (Captcha verified “yes” / Captcha not verified “no”) back to the handler. + +6, The handler API will then provide a response back to the client application. Hence a success or failure message after verification is returned to the client. + +### Steps to implement a Sample Google reCAPTCHA Solution: + + +#### Step 1: Generate the Captcha Keys: + +1, Navigate to [reCAPTCHA Admin console](https://www.google.com/recaptcha/admin) -> login with valid google account + +2, Provide “Label” (friendly name for Captcha) + +3, Select reCAPTCHA type Challenge v2 | “I’m not a robot Checkbox” + ![image](https://github.com/azure-ad-b2c/samples/assets/129459714/a0364102-9819-45ce-9081-fde2fa599d68) + +4, Under Domains, add domain name “yourtenant.b2clogin.com” (or add custom domain name if you are using custom domains for accessing b2c) + +5, Agree to the terms and conditions -> Submit. Copy the generated “Site Key” and “Secret Key” as this is needed later for captcha integration. + + +#### Step 2: Build Captcha Handler API endpoint with Azure Function App: + +*****Create an Azure Function App:***** + +1, Login to Azure Portal -> Create a resource -> Web -> choose “Function App” -> Create + +2, Select the “Subscription” and “Resource Group” + +3, Provide an apt name for “Function App name” (Eg: contosoapp) + +4, Select “Code” for deployment -> choose .NET for runtime stack -> provide version and region details + +5, Choose the Operating System (Eg: Windows) and Hosting plan (Eg: Consumption) -> Next (Storage) + +6, Provide a “Storage account” -> Next (Networking) -> select “On” for “Enable public access” -> Next (Monitoring), choose default options for “Monitoring”, “Deployment” , mention “Tags” if needed -> “Review + create” + +*****Configure the function app as a Captcha Handler API by defining a function:***** + +1, In Azure Portal, navigate to the Azure Function App -> Overview -> Functions -> Create -> Select Template “HTTP trigger” -> Create a New Function (Eg: HttpTrigger1), choose “Anonymous” Authorization level + +2, Open the function (Eg: HttpTrigger1) -> Under “Developer”, choose “Code + Test” -> choose “run.csx” from the drop down, paste the code in “run.csx” file in the sample [policies/captcha-integration/Captcha-Handler-API-AzFunc/run.csx](https://github.com/azure-ad-b2c/samples/blob/master/policies/captcha-integration/Captcha-Handler-API-AzFunc/run.csx) and save + +3, Go to the Function (Eg: HttpTrigger1) -> Overview, ensure it is enabled. + +4, Go back to the Function App -> Settings -> Configuration -> go to “Application settings” create “New application setting” -> provide name as “B2C_Recaptcha_Secret” -> Provide the “Secret Key” value given earlier by Google reCAPTCHA Services. + +5, Ensure Function App has been started (Status: Running) from the Overview tab. + +6, In this case the Captcha Handler API endpoint will be (https://function-app-name.azurewebsites.net/api/function-name) . Replace the placeholders with your function app name and function name (Eg: https://contosoapp.azurewebsites.net/api/HttpTrigger1 ) . Keep a note of this URI as this needs to be defined later in the policy. + + +#### Step 3: Build the custom policy: + +1, Use the B2C SocialAndLocalAccounts Starter Pack to build the policy. The Starter Pack can be downloaded from [SocialAndLocalAccounts](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/tree/main/SocialAndLocalAccounts) +Integrate “Captcha_TrustFrameworkExtensions.xml” and Signin.xml” + +2, Update the “data-sitekey” value in “customCaptcha.html” page with “Site Key” value generated earlier from reCAPTCHA Admin console. Also update “href” elements with proper b2c policy URLs as needed. + +3, Ensure “customCaptcha.html” is properly hosted and defined in policy file (Eg: ensure “LoadUri” elements under “ContentDefinitions” in policy file “Captcha_TrustFrameworkExtensions.xml” are properly updated as needed) + +4, Update the “ServiceUrl” metadata element for “login-Recaptcha” Technical profile with the Azure Function Captcha Handler API endpoint URI created earlier. + +5, Upload the policies and test the custom policy + +*******Additional References:******* + +[Tutorial - Create user flows and custom policies - Azure Active Directory B2C | Microsoft Learn](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy) + +[Azure Active Directory B2C custom policy overview | Microsoft Learn](https://learn.microsoft.com/en-us/azure/active-directory-b2c/custom-policy-overview)