reCAPTCHA Enterprise Connector

Use Descope's reCAPTCHA Enterprise connector to enhance the security of your authentication flows. reCAPTCHA Enterprise, a service from Google Cloud, offers comprehensive bot and online fraud protection while allowing legitimate user interactions to proceed smoothly. This guide will walk you through the configuration of the connector and its integration into your application.

Configuration

Begin by navigating to your Descope dashboard, and access the reCAPTCHA Enterprise connector configuration through: Dashboard -> Connectors -> reCAPTCHA Enterprise.

You will need to fill out the following details:

Connector Name: Assign a meaningful name to your connector for easy identification among multiple instances.
Connector Description: Briefly describe the purpose of this connector.
Project ID: Your Google Cloud project ID where reCAPTCHA Enterprise is enabled.
Site Key: The site key provided by Google for the reCAPTCHA Enterprise service.
API Key: The API key associated with your Google Cloud project.
Base URL: Apply a custom URL to the reCAPTCHA Enterprise scripts. This is useful when attempting to use reCAPTCHA globally. Defaults to https://www.google.com
Override Assessment: This is related to overriding assessment values when performing end-to-end tests. You should not use this configuration in a production environment. For details about using this configuration, see the section below for override assessment for testing.

Ensure the reCAPTCHA Enterprise API is enabled in your Google Cloud project and you have generated the necessary API key. Refer to Google's documentation for detailed instructions on enabling the API and generating keys.

Integrating reCAPTCHA Enterprise

Screen Component

Incorporate the reCAPTCHA Enterprise Privacy & Terms component in a flow screen. This initiates the CAPTCHA verification setup process for users interacting with your application.

Assessment and Annotation

Assessment: Add an "Assess" block in your flow to make a request to Google reCAPTCHA. This returns data including the user's risk scores. The main risk score (riskAnalysis.score) determines the likelihood of bot activity, while the SMS risk score (riskInfo.smsRiskScore) specifically evaluates SMS-related fraud risk.

{
 "event":{
    "expectedAction":"EXPECTED_ACTION",
    "hashedAccountId":"ACCOUNT_ID",
    "siteKey":"KEY_ID",
    "token":"TOKEN",
    "userAgent":"(USER-PROVIDED STRING)",
    "userIpAddress":"USER_PROVIDED_IP_ADDRESS"
 },
 "name":"ASSESSMENT_ID",
 "riskAnalysis":{
   "reasons":[],
   "score":"SCORE"
 },
 "riskInfo": {
   "riskScore": "SCORE",
   "botDetected": false,
   "smsRiskScore": "SCORE"
 },
 "tokenProperties":{
   "action":"USER_INTERACTION",
   "createTime":"TIMESTAMP",
   "hostname":"HOSTNAME",
   "invalidReason":"(ENUM)",
   "valid":(BOOLEAN)
 }
}

Warning

Since the reCAPTCHA connector runs in the browser, the connector steps need to be added after at least one screen or action component in the flow.

Annotation: Utilize the "Annotate" block to feed back information about the session (successful or not) to Google. This helps in refining the risk analysis for future sessions. Read more from Google here.

{
'tokenProperties': {
  'valid': True,
  'hostname': 'www.google.com',
  'action': 'homepage',
  'createTime': u'2019-03-28T12:24:17.894Z'
},
'riskAnalysis': {
  'score': 0.1,
  'reasons': ['AUTOMATION']
},
'event': {
  'token': 'RESPONSE_TOKEN',
  'siteKey': 'KEY_ID'
},
'name': 'ASSESSMENT_ID'
}

Using Assessment Data

The assessment returns two different risk scores that work inversely to each other:

Global Risk Score (riskAnalysis.score and riskInfo.riskScore): Ranges from 0.0 to 1.0, where:
- 1.0 indicates high confidence of legitimate human interaction
- 0.0 indicates high confidence of automated/bot interaction
SMS Defense Risk Score (riskInfo.smsRiskScore): Ranges from 0.0 to 1.0, but works inversely:
- 0.0 indicates low confidence of SMS toll fraud occurring
- 1.0 indicates high confidence of SMS toll fraud occurring

You can use these scores to introduce conditional logic in your flow, such as triggering additional authentication steps for users with low global risk scores or high SMS fraud risk scores.

To learn more about interpreting assess values, check out Google's docs here.

Example Flow

View an example flow configuration that leverages reCAPTCHA Enterprise for sophisticated risk analysis and fraud prevention in your application.

Check out an example flow on Descope Explorer here.

Override Assessment for Testing

Descope allows you to override the assessment value within the Recaptcha Enterprise connector. Overriding the assessment s helpful in a few scenarios like automated end-to-end testing where you do not want to fail on Recaptcha assessment or testing scenarios where you do want to fail Recaptcha assessment.

To configure the overriding of the Recaptcha assessment within the Recaptcha Enterprise connector configuration, check the box Override Assessment (For Testing). You can then set the Assessment score; when configured, the Recaptcha action will return the score without assessing the request. The score ranges between 0 and 1, where 1 is a human interaction, and 0 is a bot.

Additional Resources

For a deeper dive into configuring and utilizing reCAPTCHA Enterprise within Descope, refer to the additional resources and documentation provided by Google Cloud and Descope. These resources offer comprehensive guidance on setting up reCAPTCHA Enterprise for optimal security and fraud prevention in your digital applications.

Was this helpful?

reCAPTCHA Enterprise Connector

On this page