Skip to content

Commit acd83f4

Browse files
ethanpalmethanpalm
committed
add shared session info
1 parent 8738911 commit acd83f4

File tree

1 file changed

+118
-10
lines changed

1 file changed

+118
-10
lines changed

‎authentication-personalization/personalization-setup.mdx‎

Lines changed: 118 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -87,23 +87,131 @@ To redirect users to specific sections after login, use this URL format: `https:
8787
</Tab>
8888
<Tab title="OAuth 2.0">
8989
### Prerequisites
90-
- You have an existing OAuth server that supports the PKCE flow.
91-
- You can create a new API endpoint that can be accessed by the returned OAuth access token.
90+
* An OAuth server that supports the PKCE Flow.
91+
* Ability to create an API endpoint accessible by OAuth access tokens
92+
9293
### Implementation
94+
<Steps>
95+
<Step title="Create user info API endpoint.">
96+
Create an API endpoint that:
97+
* Accepts OAuth access tokens for authentication.
98+
* Returns user data in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information.
99+
* Defines the scopes for access.
100+
</Step>
101+
<Step title="Configure your OAuth personalization settings.">
102+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
103+
2. Select **Personalization**.
104+
3. Select **OAuth** and configure these fields:
105+
* **Authorization URL**: Your OAuth authorization endpoint.
106+
* **Client ID**: Your OAuth 2.0 client identifier.
107+
* **Scopes**: Permissions to request. Must match the scopes of the endpoint that you configured in the first step.
108+
* **Token URL**: Your OAuth token exchange endpoint.
109+
* **Info API URL**: Endpoint to retrieve user data for personalization. Created in the first step.
110+
4. Select **Save changes**
111+
</Step>
112+
<Step title="Configure your OAuth server.">
113+
1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
114+
2. Add this URL as an authorized redirect URL in your OAuth server configuration.
115+
</Step>
116+
</Steps>
117+
118+
### Example
119+
120+
Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data.
121+
122+
**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope and responds with the user's custom data:
123+
124+
```json
125+
{
126+
"content": {
127+
"firstName": "Jane",
128+
"lastName": "Doe"
129+
},
130+
"groups": ["engineering", "admin"]
131+
}
132+
```
133+
134+
**Configure your OAuth server details** in your dashboard:
135+
- **Authorization URL**: `https://auth.foo.com/authorization`
136+
- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
137+
- **Scopes**: `['docs-user-info']`
138+
- **Token URL**: `https://auth.foo.com/exchange`
139+
- **Info API URL**: `https://api.foo.com/docs/user-info`
140+
141+
**Configure your OAuth server** to allow redirects to your callback URL.
93142
</Tab>
94143
<Tab title="Shared session">
95144
### Prerequisites
96145

97-
- You have a dashboard or other user portal hosted at your domain.
98-
- Your users' session credentials are stored as cookies.
99-
- You can create a new API endpoint at the same origin or a subdomain of your dashboard.
100-
- If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`
101-
- If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`
102-
- Your docs are hosted at the same domain as your dashboard.
103-
- If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`
104-
- If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`
146+
* A dashboard or user portal with cookie-based session authentication.
147+
* Ability to create an API endpoint at the same origin or subdomain as your dashboard.
148+
* If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`.
149+
* If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`.
150+
* Your docs are hosted at the same domain or subdomain as your dashboard.
151+
* If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`.
152+
* If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`.
105153

106154
### Implementation
155+
156+
<Steps>
157+
<Step title="Create user info API endpoint.">
158+
Create an API endpoint that:
159+
* Uses your existing session authentication to identify users
160+
* Returns user data in the `User` format (see [Sending Data](/authentication-personalization/sending-data))
161+
* If the API domain and the docs domain **do not exactly match**:
162+
- Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`).
163+
- Set your API's `Access-Control-Allow-Credentials` header to `true`.
164+
165+
<Warning>
166+
Only enable CORS headers on this specific endpoint, not your entire dashboard API.
167+
</Warning>
168+
</Step>
169+
<Step title="Configure your personalization settings">
170+
Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the API URL and your Login URL to your Personalization settings.
171+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
172+
2. Select **Personalization**.
173+
3. Select **Shared Session**.
174+
4. Enter your **Info API URL**, which is the endpoint from the first step.
175+
5. Enter your **Login URL**, where users log in to your dashboard.
176+
6. Select **Save changes**
177+
</Step>
178+
</Steps>
179+
180+
### Examples
181+
182+
#### Dashboard at subdomain, docs at subdomain
183+
184+
You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `docs.foo.com`.
185+
186+
**Setup process**:
187+
1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data.
188+
2. **Add CORS headers** for this route only:
189+
* `Access-Control-Allow-Origin`: `https://docs.foo.com`
190+
* `Access-Control-Allow-Credentials`: `true`
191+
3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`.
192+
193+
### Dashboard at subdomain, docs at root
194+
195+
You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`.
196+
197+
**Setup process**:
198+
1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data.
199+
2. **Add CORS headers** for this route only:
200+
- `Access-Control-Allow-Origin`: `https://foo.com`
201+
- `Access-Control-Allow-Credentials`: `true`
202+
3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`.
203+
204+
### Dashboard at root, docs at root
205+
206+
You have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`.
207+
208+
**Setup process**:
209+
1. **Create endpoint** `foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data.
210+
2. **Configure API URL** in authentication settings: `https://foo.com/api/docs/user-info`
211+
212+
<Note>
213+
No CORS configuration is needed since the dashboard and docs share the same domain.
214+
</Note>
107215
</Tab>
108216
</Tabs>
109217

0 commit comments

Comments
 (0)