Merge pull request #698 from Kitware/improve-auth-docs

docs: add CORS note to tokenUrl

Author: floryst

docs/.vitepress/config.ts

@@ -59,7 +59,7 @@ export default defineConfig({
           { text: 'Overview', link: '/deployment_overview' },
           { text: 'Building for Production', link: '/building_for_production' },
           { text: 'Deploying VolView', link: '/deploying_volview' },
-          { text: 'Authentication', link: '/authentication' },
+          { text: 'Authentication & Authorization', link: '/authentication' },
           { text: 'Cross Origin Resource Sharing (CORS)', link: '/cors' },
         ],
       },

docs/authentication.md

@@ -1,4 +1,4 @@
-# Authentication
+# Authentication & Authorization
 
 VolView itself does not specify any given authentication mechanism to use. How you let VolView access authenticated resources depends on individual deployment needs.
 
@@ -21,4 +21,9 @@ You can pass in the `token` URL parameter like so: `https://example.com/VolView/
 
 As an alternative to passing in the token via the URL, if you have an endpoint that returns the user's token then you can use the `tokenUrl` parameter like so: `https://example.com/VolView/?tokenUrl=https://example.com/userToken`. If VolView successfully receives a token from this endpoint, it will use the token in subsequent data requests.
 
-By default, VolView will make a `GET` request to the token URL. If another type of request is needed, you can configure it via the `tokenUrlMethod` parameter. For example, to make a `POST` request: `https:/example.com/VolView/?tokenUrl=https://example.com/userToken&tokenUrlMethod=POST`.
+The token URL is expected to return the access token as plaintext, i.e. `text/plain`. Please note that you cannot use an OAuth token endpoint here! OAuth token endpoints are used to exchange auth information, while `tokenUrl` must return just the access token under an already-authenticated session.
+
+By default, VolView will make a `GET` request to the token URL. If another type of request is needed, you can configure it via the `tokenUrlMethod` parameter. For example, to make a `POST` request: `https:/example.com/VolView/?tokenUrl=https://example.com/userToken&tokenUrlMethod=POST`.
+
+> [!NOTE]
+> This requires CORS to be properly configured for the token URL endpoint. See the [CORS](/cors) documentation for more info.

docs/cors.md

@@ -18,7 +18,9 @@ Please see [the deployment docs](/deploying_volview) for more info on what an ex
 server {
     ...
 
-    add_header Access-Control-Allow-Origin "example.com"
+    # Replace "volview.kitware.app" with the domain on which
+    # VolView is being hosted.
+    add_header Access-Control-Allow-Origin "volview.kitware.app"
 }
 ```