fix: (DeclarativeOAuthFlow) - make the extract_output Optional; correct the descriptions (#106)

bazarnov · bnchrch · web-flow · commit 94b019840a57 · 2025-01-23T13:14:10.000+02:00
Co-authored-by: Ben Church &lt;ben@airbyte.io&gt;
diff --git a/protocol-models/src/main/resources/airbyte_protocol/airbyte_protocol.yaml b/protocol-models/src/main/resources/airbyte_protocol/airbyte_protocol.yaml
@@ -663,7 +663,6 @@ definitions:
         required: 
           - consent_url
           - access_token_url
-          - extract_output
         properties:
           consent_url: 
             type: string
@@ -673,7 +672,7 @@ definitions:
 
               Examples:
                 {
-                  "consent_url": "https://domain.host.com/oauth2/authorize?{client_id_key}={{client_id_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}&{scope_key}={urlEncoder:{{scope_key}}}&{state_key}={{state_key}}&subdomain={subdomain}"
+                  "consent_url": "https://domain.host.com/oauth2/authorize?{{ client_id_key }}={{ client_id_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_value}} | urlEncoder }}&{{ scope_key }}={{ {{scope_key}} | urlEncoder }}&{{ state_key }}={{ state_value }}&subdomain={{ subdomain }}"
                 }
           scope: 
             type: string
@@ -692,7 +691,7 @@ definitions:
 
               Examples:
                 {
-                  "access_token_url": https://auth.host.com/oauth2/token?{client_id_key}={{client_id_key}}&{client_secret_key}={{client_secret_key}}&{auth_code_key}={{auth_code_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}
+                  "access_token_url": "https://auth.host.com/oauth2/token?{{ client_id_key }}={{ client_id_value }}&{{ client_secret_key }}={{ client_secret_value }}&{{ auth_code_key }}={{ auth_code_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_key}} | urlEncoder }}"
                 }
           access_token_headers:
             type: object
@@ -706,7 +705,7 @@ definitions:
 
                 {
                   "access_token_headers": {
-                      "Authorization": "Basic {base64Encoder:{client_id}:{client_secret}}"
+                      "Authorization": "Basic {{ {{ client_id_value }}:{{ client_secret_value }} | base64Encoder }}"
                   }
                 }
           access_token_params:
@@ -720,7 +719,7 @@ definitions:
                 {
                   "access_token_params": {
                       "my_query_param": "param_value",
-                      "{client_id_key}": {{client_id_key}}
+                      "{{ client_id_key }}": "{{ client_id_value }}"
                   }
                 }
           extract_output:
@@ -810,6 +809,15 @@ definitions:
                 {
                   "redirect_uri_key": "my_custom_redirect_uri_key_name"
                 }
+          token_expiry_key:
+            type: string
+            description: |-
+              The OAuth Specific optional override to provide the custom key name to something like `expires_at`, if required by data-provider.
+
+              Examples:
+                {
+                  "token_expiry_key": "expires_at"
+                }
         existingJavaType: com.fasterxml.jackson.databind.JsonNode
       complete_oauth_output_specification:
         description: |-
@@ -819,11 +827,23 @@ definitions:
           For each field, a special annotation `path_in_connector_config` can be specified to determine where to merge it,
 
           Examples:
+              With a `refresh_token` in the `oauth response`:
 
               complete_oauth_output_specification={
                 refresh_token: {
                   type: string,
-                  path_in_connector_config: ['credentials', 'refresh_token']
+                  path_in_connector_config: ['credentials', 'refresh_token'],
+                  path_in_oauth_response: ['refresh_token']
+                }
+              }
+              
+              With a nested `refresh_token` under the `data` object, in the `oauth response`:
+              
+              complete_oauth_output_specification={
+                refresh_token: {
+                  type: string,
+                  path_in_connector_config: ['credentials', 'refresh_token'],
+                  path_in_oauth_response: ['data', 'refresh_token']
                 }
               }
         type: object
diff --git a/protocol-models/src/main/resources/airbyte_protocol/v0/airbyte_protocol.yaml b/protocol-models/src/main/resources/airbyte_protocol/v0/airbyte_protocol.yaml
@@ -718,7 +718,6 @@ definitions:
         required: 
           - consent_url
           - access_token_url
-          - extract_output
         properties:
           consent_url: 
             type: string
@@ -728,7 +727,7 @@ definitions:
 
               Examples:
                 {
-                  "consent_url": "https://domain.host.com/oauth2/authorize?{client_id_key}={{client_id_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}&{scope_key}={urlEncoder:{{scope_key}}}&{state_key}={{state_key}}&subdomain={subdomain}"
+                  "consent_url": "https://domain.host.com/oauth2/authorize?{{ client_id_key }}={{ client_id_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_value}} | urlEncoder }}&{{ scope_key }}={{ {{scope_key}} | urlEncoder }}&{{ state_key }}={{ state_value }}&subdomain={{ subdomain }}"
                 }
           scope: 
             type: string
@@ -747,7 +746,7 @@ definitions:
 
               Examples:
                 {
-                  "access_token_url": https://auth.host.com/oauth2/token?{client_id_key}={{client_id_key}}&{client_secret_key}={{client_secret_key}}&{auth_code_key}={{auth_code_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}
+                  "access_token_url": "https://auth.host.com/oauth2/token?{{ client_id_key }}={{ client_id_value }}&{{ client_secret_key }}={{ client_secret_value }}&{{ auth_code_key }}={{ auth_code_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_key}} | urlEncoder }}"
                 }
           access_token_headers:
             type: object
@@ -761,7 +760,7 @@ definitions:
 
                 {
                   "access_token_headers": {
-                      "Authorization": "Basic {base64Encoder:{client_id}:{client_secret}}"
+                      "Authorization": "Basic {{ {{ client_id_value }}:{{ client_secret_value }} | base64Encoder }}"
                   }
                 }
           access_token_params:
@@ -775,7 +774,7 @@ definitions:
                 {
                   "access_token_params": {
                       "my_query_param": "param_value",
-                      "{client_id_key}": {{client_id_key}}
+                      "{{ client_id_key }}": "{{ client_id_value }}"
                   }
                 }
           extract_output:
@@ -865,6 +864,15 @@ definitions:
                 {
                   "redirect_uri_key": "my_custom_redirect_uri_key_name"
                 }
+          token_expiry_key:
+            type: string
+            description: |-
+              The OAuth Specific optional override to provide the custom key name to something like `expires_at`, if required by data-provider.
+
+              Examples:
+                {
+                  "token_expiry_key": "expires_at"
+                }
         existingJavaType: com.fasterxml.jackson.databind.JsonNode
       complete_oauth_output_specification:
         description: |-
@@ -874,11 +882,23 @@ definitions:
           For each field, a special annotation `path_in_connector_config` can be specified to determine where to merge it,
 
           Examples:
+              With a `refresh_token` in the `oauth response`:
 
               complete_oauth_output_specification={
                 refresh_token: {
                   type: string,
-                  path_in_connector_config: ['credentials', 'refresh_token']
+                  path_in_connector_config: ['credentials', 'refresh_token'],
+                  path_in_oauth_response: ['refresh_token']
+                }
+              }
+              
+              With a nested `refresh_token` under the `data` object, in the `oauth response`:
+              
+              complete_oauth_output_specification={
+                refresh_token: {
+                  type: string,
+                  path_in_connector_config: ['credentials', 'refresh_token'],
+                  path_in_oauth_response: ['data', 'refresh_token']
                 }
               }
         type: object

Original file line number	Diff line number	Diff line change
`@@ -663,7 +663,6 @@ definitions:`
`663`	`663`	`required:`
`664`	`664`	`- consent_url`
`665`	`665`	`- access_token_url`
`666`		`- - extract_output`
`667`	`666`	`properties:`
`668`	`667`	`consent_url:`
`669`	`668`	`type: string`
`@@ -673,7 +672,7 @@ definitions:`
`673`	`672`
`674`	`673`	`Examples:`
`675`	`674`	`{`
`676`		`- "consent_url": "https://domain.host.com/oauth2/authorize?{client_id_key}={{client_id_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}&{scope_key}={urlEncoder:{{scope_key}}}&{state_key}={{state_key}}&subdomain={subdomain}"`
	`675`	`+ "consent_url": "https://domain.host.com/oauth2/authorize?{{ client_id_key }}={{ client_id_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_value}} \| urlEncoder }}&{{ scope_key }}={{ {{scope_key}} \| urlEncoder }}&{{ state_key }}={{ state_value }}&subdomain={{ subdomain }}"`
`677`	`676`	`}`
`678`	`677`	`scope:`
`679`	`678`	`type: string`
`@@ -692,7 +691,7 @@ definitions:`
`692`	`691`
`693`	`692`	`Examples:`
`694`	`693`	`{`
`695`		`- "access_token_url": https://auth.host.com/oauth2/token?{client_id_key}={{client_id_key}}&{client_secret_key}={{client_secret_key}}&{auth_code_key}={{auth_code_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}`
	`694`	`+ "access_token_url": "https://auth.host.com/oauth2/token?{{ client_id_key }}={{ client_id_value }}&{{ client_secret_key }}={{ client_secret_value }}&{{ auth_code_key }}={{ auth_code_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_key}} \| urlEncoder }}"`
`696`	`695`	`}`
`697`	`696`	`access_token_headers:`
`698`	`697`	`type: object`
`@@ -706,7 +705,7 @@ definitions:`
`706`	`705`
`707`	`706`	`{`
`708`	`707`	`"access_token_headers": {`
`709`		`- "Authorization": "Basic {base64Encoder:{client_id}:{client_secret}}"`
	`708`	`+ "Authorization": "Basic {{ {{ client_id_value }}:{{ client_secret_value }} \| base64Encoder }}"`
`710`	`709`	`}`
`711`	`710`	`}`
`712`	`711`	`access_token_params:`
`@@ -720,7 +719,7 @@ definitions:`
`720`	`719`	`{`
`721`	`720`	`"access_token_params": {`
`722`	`721`	`"my_query_param": "param_value",`
`723`		`- "{client_id_key}": {{client_id_key}}`
	`722`	`+ "{{ client_id_key }}": "{{ client_id_value }}"`
`724`	`723`	`}`
`725`	`724`	`}`
`726`	`725`	`extract_output:`
`@@ -810,6 +809,15 @@ definitions:`
`810`	`809`	`{`
`811`	`810`	`"redirect_uri_key": "my_custom_redirect_uri_key_name"`
`812`	`811`	`}`
	`812`	`+ token_expiry_key:`
	`813`	`+ type: string`
	`814`	`+ description: \|-`
	`815`	+ The OAuth Specific optional override to provide the custom key name to something like `expires_at`, if required by data-provider.
	`816`	`+`
	`817`	`+ Examples:`
	`818`	`+ {`
	`819`	`+ "token_expiry_key": "expires_at"`
	`820`	`+ }`
`813`	`821`	`existingJavaType: com.fasterxml.jackson.databind.JsonNode`
`814`	`822`	`complete_oauth_output_specification:`
`815`	`823`	`description: \|-`
`@@ -819,11 +827,23 @@ definitions:`
`819`	`827`	For each field, a special annotation `path_in_connector_config` can be specified to determine where to merge it,
`820`	`828`
`821`	`829`	`Examples:`
	`830`	+ With a `refresh_token` in the `oauth response`:
`822`	`831`
`823`	`832`	`complete_oauth_output_specification={`
`824`	`833`	`refresh_token: {`
`825`	`834`	`type: string,`
`826`		`- path_in_connector_config: ['credentials', 'refresh_token']`
	`835`	`+ path_in_connector_config: ['credentials', 'refresh_token'],`
	`836`	`+ path_in_oauth_response: ['refresh_token']`
	`837`	`+ }`
	`838`	`+ }`
	`839`	`+`
	`840`	+ With a nested `refresh_token` under the `data` object, in the `oauth response`:
	`841`	`+`
	`842`	`+ complete_oauth_output_specification={`
	`843`	`+ refresh_token: {`
	`844`	`+ type: string,`
	`845`	`+ path_in_connector_config: ['credentials', 'refresh_token'],`
	`846`	`+ path_in_oauth_response: ['data', 'refresh_token']`
`827`	`847`	`}`
`828`	`848`	`}`
`829`	`849`	`type: object`
Original file line number	Diff line number	Diff line change
`@@ -718,7 +718,6 @@ definitions:`
`718`	`718`	`required:`
`719`	`719`	`- consent_url`
`720`	`720`	`- access_token_url`
`721`		`- - extract_output`
`722`	`721`	`properties:`
`723`	`722`	`consent_url:`
`724`	`723`	`type: string`
`@@ -728,7 +727,7 @@ definitions:`
`728`	`727`
`729`	`728`	`Examples:`
`730`	`729`	`{`
`731`		`- "consent_url": "https://domain.host.com/oauth2/authorize?{client_id_key}={{client_id_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}&{scope_key}={urlEncoder:{{scope_key}}}&{state_key}={{state_key}}&subdomain={subdomain}"`
	`730`	`+ "consent_url": "https://domain.host.com/oauth2/authorize?{{ client_id_key }}={{ client_id_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_value}} \| urlEncoder }}&{{ scope_key }}={{ {{scope_key}} \| urlEncoder }}&{{ state_key }}={{ state_value }}&subdomain={{ subdomain }}"`
`732`	`731`	`}`
`733`	`732`	`scope:`
`734`	`733`	`type: string`
`@@ -747,7 +746,7 @@ definitions:`
`747`	`746`
`748`	`747`	`Examples:`
`749`	`748`	`{`
`750`		`- "access_token_url": https://auth.host.com/oauth2/token?{client_id_key}={{client_id_key}}&{client_secret_key}={{client_secret_key}}&{auth_code_key}={{auth_code_key}}&{redirect_uri_key}={urlEncoder:{{redirect_uri_key}}}`
	`749`	`+ "access_token_url": "https://auth.host.com/oauth2/token?{{ client_id_key }}={{ client_id_value }}&{{ client_secret_key }}={{ client_secret_value }}&{{ auth_code_key }}={{ auth_code_value }}&{{ redirect_uri_key }}={{ {{redirect_uri_key}} \| urlEncoder }}"`
`751`	`750`	`}`
`752`	`751`	`access_token_headers:`
`753`	`752`	`type: object`
`@@ -761,7 +760,7 @@ definitions:`
`761`	`760`
`762`	`761`	`{`
`763`	`762`	`"access_token_headers": {`
`764`		`- "Authorization": "Basic {base64Encoder:{client_id}:{client_secret}}"`
	`763`	`+ "Authorization": "Basic {{ {{ client_id_value }}:{{ client_secret_value }} \| base64Encoder }}"`
`765`	`764`	`}`
`766`	`765`	`}`
`767`	`766`	`access_token_params:`
`@@ -775,7 +774,7 @@ definitions:`
`775`	`774`	`{`
`776`	`775`	`"access_token_params": {`
`777`	`776`	`"my_query_param": "param_value",`
`778`		`- "{client_id_key}": {{client_id_key}}`
	`777`	`+ "{{ client_id_key }}": "{{ client_id_value }}"`
`779`	`778`	`}`
`780`	`779`	`}`
`781`	`780`	`extract_output:`
`@@ -865,6 +864,15 @@ definitions:`
`865`	`864`	`{`
`866`	`865`	`"redirect_uri_key": "my_custom_redirect_uri_key_name"`
`867`	`866`	`}`
	`867`	`+ token_expiry_key:`
	`868`	`+ type: string`
	`869`	`+ description: \|-`
	`870`	+ The OAuth Specific optional override to provide the custom key name to something like `expires_at`, if required by data-provider.
	`871`	`+`
	`872`	`+ Examples:`
	`873`	`+ {`
	`874`	`+ "token_expiry_key": "expires_at"`
	`875`	`+ }`
`868`	`876`	`existingJavaType: com.fasterxml.jackson.databind.JsonNode`
`869`	`877`	`complete_oauth_output_specification:`
`870`	`878`	`description: \|-`
`@@ -874,11 +882,23 @@ definitions:`
`874`	`882`	For each field, a special annotation `path_in_connector_config` can be specified to determine where to merge it,
`875`	`883`
`876`	`884`	`Examples:`
	`885`	+ With a `refresh_token` in the `oauth response`:
`877`	`886`
`878`	`887`	`complete_oauth_output_specification={`
`879`	`888`	`refresh_token: {`
`880`	`889`	`type: string,`
`881`		`- path_in_connector_config: ['credentials', 'refresh_token']`
	`890`	`+ path_in_connector_config: ['credentials', 'refresh_token'],`
	`891`	`+ path_in_oauth_response: ['refresh_token']`
	`892`	`+ }`
	`893`	`+ }`
	`894`	`+`
	`895`	+ With a nested `refresh_token` under the `data` object, in the `oauth response`:
	`896`	`+`
	`897`	`+ complete_oauth_output_specification={`
	`898`	`+ refresh_token: {`
	`899`	`+ type: string,`
	`900`	`+ path_in_connector_config: ['credentials', 'refresh_token'],`
	`901`	`+ path_in_oauth_response: ['data', 'refresh_token']`
`882`	`902`	`}`
`883`	`903`	`}`
`884`	`904`	`type: object`