📝 Session Token Authenticator documentation #28762

lmossman · 2023-07-27T00:24:32Z

What

Relates to #26901

How

Updates the Connector Builder authentication documentation to explain when and how to use the Session Token authenticator.

flash1293 · 2023-07-27T12:58:41Z

docs/connector-development/connector-builder-ui/authentication.md

@@ -143,6 +144,47 @@ In a lot of cases, OAuth refresh tokens are long-lived and can be used to create

 This can be done using the "Overwrite config with refresh token response" setting. If enabled, the authenticator expects a new refresh token to be returned from the token refresh endpoint. By default, the property `refresh_token` is used to extract the new refresh token, but this can be configured using the "Refresh token property name" setting. The connector then updates its own configuration with the new refresh token and uses it the next time an access token needs to be generated. If this option is used, it's necessary to specify an initial access token along with its expiry date in the "Testing values" menu.

+### Session Token


We should also update docs/connector-development/connector-builder-ui/connector-builder-compatibility.md to mention this as a supported type (there's another error on that page about single-use refresh token which are supported now, could you fix that as well)?

Good callout, added

flash1293 · 2023-07-27T13:00:31Z

docs/connector-development/connector-builder-ui/authentication.md

+  - `Request Headers` - used to attach headers to the sesssion token retrieval request
+    - Metabase does not require any headers in the `/api/session` request, so this is left unset.
+  - `Request Body` - used to attach a request body to the session token retrieval request
+    - As mentioned above, Metabase requires the username and password to be sent in the request body, so we can select `JSON (key-value pairs)` here and set the username and password fields (using User Inputs for the values to make the connector reusable).


Could you spell out the keys and values here that need to be set?

flash1293 · 2023-07-27T13:01:22Z

docs/connector-development/connector-builder-ui/authentication.md

+  - For Metabase, the `/api/session` response looks like `{"id":"<session-token-value>"}`, so the value here would simply be `id`.
+- `Expiration Duration` - an [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) indicating how long the session token has until it expires
+  - Once this duration is reached, your connector will automatically fetch a new session token, and continue making data requests with that new one.
+  - If this is left unset, the session token will be refreshed before every single data request.


Could we add a note here that in most cases it makes sense to set the expiration date as the connector will run much slower than necessary otherwise?

flash1293 · 2023-07-27T13:02:20Z

docs/connector-development/connector-builder-ui/authentication.md

+  - Choose `API Key` if your session token needs to be injected into a query parameter or header of the data requests.
+    - Metabase takes in the session token through a specific header, so this would be set to `API Key`, Inject Session Token into outgoing HTTP Request would be set to `Header`, and Header Name would be set to `X-Metabase-Session`.
+  - Choose `Bearer` if your session token needs to be sent as a standard Bearer token.
+


Could we add a note that the session token authenticator does not support dynamic expiration dates of the session token and that the expiration duration should be set to the expected minimum to avoid problems during syncing?

Good idea, added

flash1293

LGTM, thanks

Marcaccio-Mutt · 2023-12-06T21:16:30Z

Hello!

Is this documentation updated? I dont find any example about "How configure Session Token"

lmossman · 2023-12-06T21:20:53Z

@Marcaccio-Mutt you can find the session token authentication documentation for the Connector Builder here: https://docs.airbyte.com/connector-development/connector-builder-ui/authentication#session-token

Marcaccio-Mutt · 2023-12-06T21:38:40Z

Thx!

Is all this configuration inside the yaml file? Is there some example that how configure it?

lmossman · 2023-12-06T21:41:34Z

@Marcaccio-Mutt That documentation is focused on explaining how to configure the session token authenticator in the Connector Builder UI, but the same ideas are applicable to the YAML manifest file as well (as the Connector Builder UI is just a layer on top of the YAML, and produces a low-code YAML manifest as output)

You can see an example of this in the source-dockerhub connector:

airbyte/airbyte-integrations/connectors/source-dockerhub/source_dockerhub/manifest.yaml

Lines 22 to 42 in 62b2020

    
                   authenticator: 
        
                     type: SessionTokenAuthenticator 
        
                     login_requester: 
        
                       type: HttpRequester 
        
                       url_base: >- 
        
                         https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/alpine:pull/ 
        
                       path: "" 
        
                       authenticator: 
        
                         type: NoAuth 
        
                       http_method: GET 
        
                       request_parameters: {} 
        
                       request_headers: {} 
        
                       request_body_json: {} 
        
                     session_token_path: 
        
                       - token 
        
                     request_authentication: 
        
                       type: ApiKey 
        
                       inject_into: 
        
                         type: RequestOption 
        
                         field_name: Authorization 
        
                         inject_into: header

add documentation for session token authenticator

6d752b0

lmossman requested a review from flash1293 July 27, 2023 00:24

octavia-squidington-iii added the area/documentation Improvements or additions to documentation label Jul 27, 2023

flash1293 reviewed Jul 27, 2023

View reviewed changes

lmossman added 4 commits July 27, 2023 16:19

fix refresh token statements in compatibility guide

a4ff251

add blurb about session token auth to compatibility guide

a3d4e06

spell out keys and values

4ea9eb7

add a couple more comments

458ebc1

lmossman requested a review from flash1293 July 27, 2023 23:33

flash1293 approved these changes Jul 31, 2023

View reviewed changes

lmossman merged commit c542ceb into master Jul 31, 2023

lmossman deleted the lmossman/session-token-auth-docs branch July 31, 2023 17:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📝 Session Token Authenticator documentation #28762

📝 Session Token Authenticator documentation #28762

lmossman commented Jul 27, 2023

flash1293 Jul 27, 2023

lmossman Jul 27, 2023

flash1293 Jul 27, 2023

lmossman Jul 27, 2023

flash1293 Jul 27, 2023

flash1293 Jul 27, 2023

lmossman Jul 27, 2023

flash1293 left a comment

Marcaccio-Mutt commented Dec 6, 2023

lmossman commented Dec 6, 2023 •

edited

Loading

Marcaccio-Mutt commented Dec 6, 2023

lmossman commented Dec 6, 2023

		@@ -143,6 +144,47 @@ In a lot of cases, OAuth refresh tokens are long-lived and can be used to create

		This can be done using the "Overwrite config with refresh token response" setting. If enabled, the authenticator expects a new refresh token to be returned from the token refresh endpoint. By default, the property `refresh_token` is used to extract the new refresh token, but this can be configured using the "Refresh token property name" setting. The connector then updates its own configuration with the new refresh token and uses it the next time an access token needs to be generated. If this option is used, it's necessary to specify an initial access token along with its expiry date in the "Testing values" menu.

		### Session Token

📝 Session Token Authenticator documentation #28762

📝 Session Token Authenticator documentation #28762

Conversation

lmossman commented Jul 27, 2023

What

How

flash1293 Jul 27, 2023

Choose a reason for hiding this comment

lmossman Jul 27, 2023

Choose a reason for hiding this comment

flash1293 Jul 27, 2023

Choose a reason for hiding this comment

lmossman Jul 27, 2023

Choose a reason for hiding this comment

flash1293 Jul 27, 2023

Choose a reason for hiding this comment

flash1293 Jul 27, 2023

Choose a reason for hiding this comment

lmossman Jul 27, 2023

Choose a reason for hiding this comment

flash1293 left a comment

Choose a reason for hiding this comment

Marcaccio-Mutt commented Dec 6, 2023

lmossman commented Dec 6, 2023 • edited Loading

Marcaccio-Mutt commented Dec 6, 2023

lmossman commented Dec 6, 2023

lmossman commented Dec 6, 2023 •

edited

Loading