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.
API Key: The API key associated with your Google Cloud project.
Site Key: The site key provided by Google for the reCAPTCHA Enterprise service.
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 riskScore, which is crucial for determining the legitimacy of a user session.

{
 "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"
 },
 "tokenProperties":{
   "action":"USER_INTERACTION",
   "createTime":"TIMESTAMP",
   "hostname":"HOSTNAME",
   "invalidReason":"(ENUM)",
   "valid":(BOOLEAN)
 }
}

Annotation: Utilize the "Annotate" block to feedback 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

Employ the data returned from the assessment to introduce conditional logic in your flow, such as triggering additional authentication steps for users identified as high-risk. 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. Below you can see an example of the configured Recaptcha Enterprise connector configured to return a human interaction for the overridden assessment.

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?

On this page