docs: add workos tpa docs (supabase#36662)

* docs: add workos to 3rd party auth docs

* Commit @charislam's suggestions

Co-authored-by: Charis <[email protected]>

* more explanation of the user_role claim

* drop CLI instructions for now

* add WorkOS to nav menu

* fix typo

* use issuer not client id

* fix prettier

---------

Co-authored-by: Cameron Matheson <[email protected]>
Co-authored-by: Cameron Matheson <[email protected]>
Co-authored-by: Charis <[email protected]>

Author: 3 people

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -663,6 +663,7 @@ export const auth = {
         { name: 'Firebase Auth', url: '/guides/auth/third-party/firebase-auth' },
         { name: 'Auth0', url: '/guides/auth/third-party/auth0' },
         { name: 'AWS Cognito (Amplify)', url: '/guides/auth/third-party/aws-cognito' },
+        { name: 'WorkOS', url: '/guides/auth/third-party/workos' },
       ],
     },
     {

apps/docs/content/guides/auth/third-party/overview.mdx

@@ -10,6 +10,7 @@ Supabase has first-class support for these third-party authentication providers:
 - [Firebase Auth](/docs/guides/auth/third-party/firebase-auth)
 - [Auth0](/docs/guides/auth/third-party/auth0)
 - [AWS Cognito (with or without AWS Amplify)](/docs/guides/auth/third-party/aws-cognito)
+- [WorkOS](/docs/guides/auth/third-party/workos)
 
 You can use these providers alongside Supabase Auth, or on their own, to access the [Data API (REST and GraphQL)](/docs/guides/database), [Storage](/docs/guides/storage), [Realtime](/docs/guides/storage) and [Functions](/docs/guides/functions) from your existing apps.
 

apps/docs/content/guides/auth/third-party/workos.mdx

@@ -0,0 +1,57 @@
+---
+id: 'auth-third-party-workos'
+title: 'WorkOS'
+subtitle: 'Use WorkOS with your Supabase project'
+---
+
+WorkOS can be used as a third-party authentication provider alongside Supabase Auth, or standalone, with your Supabase project.
+
+## Getting started
+
+1. First you need to add an integration to connect your Supabase project with your WorkOS tenant. You will need your WorkOS issuer. The issuer is `https://api.workos.com/user_management/<your-client-id>`. Substitute your [custom auth domain](https://workos.com/docs/custom-domains/auth-api) for "api.workos.com" if configured.
+2. Add a new Third-party Auth integration in your project's [Authentication settings](/dashboard/project/_/settings/auth).
+3. Set up a JWT template to assign the `role: 'authenticated'` claim to your access token.
+
+## Setup the Supabase client library
+
+<Tabs type="underlined" queryGroup="language">
+
+<TabPanel id="ts" label="TypeScript">
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import { createClient as createAuthKitClient } from '@workos-inc/authkit-js'
+
+const authkit = await createAuthKitClient('WORKOS_CLIENT_ID', {
+  apiHostname: '<WORKOS_AUTH_DOMAIN>',
+})
+
+const supabase = createClient('https://<supabase-project>.supabase.co', 'SUPABASE_ANON_KEY', {
+  accessToken: async () => {
+    return authkit.getAccessToken()
+  },
+})
+```
+
+</TabPanel>
+
+</Tabs>
+
+## Add a new Third-Party Auth integration to your project
+
+In the dashboard navigate to your project's [Authentication settings](/dashboard/project/_/settings/auth) and find the Third-Party Auth section to add a new integration.
+
+## Set up a JWT template to add the authenticated role.
+
+Your Supabase project inspects the `role` claim present in all JWTs sent to it, to assign the correct Postgres role when using the Data API, Storage or Realtime authorization.
+
+WorkOS JWTs already contain a `role` claim that corresponds to the user's role in their organization. It is necessary to adjust the `role` claim to be `"authenticated"` like Supabase expects. This can be done using JWT templates (navigate to Authentication -> Sessions -> JWT Template in the WorkOS Dashboard).
+
+This template overrides the `role` claim to meet Supabase's expectations, and adds the WorkOS role in a new `user_role` claim:
+
+```json
+{
+  "role": "authenticated",
+  "user_role": {{organization_membership.role}}
+}
+```