@servicetitan/docs-uikit 28.4.0 → 28.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/ajax-handlers.mdx +67 -8
- package/package.json +2 -2
package/docs/ajax-handlers.mdx
CHANGED
|
@@ -61,7 +61,7 @@ const App = () => {
|
|
|
61
61
|
| Name | Type | Description |
|
|
62
62
|
| :------------------------ | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
63
63
|
| `authAdapter` | <code>string | Function</code> | (optional) authentication scheme ([see below](#auth-adapter)). Defaults to **Bearer** authentication. |
|
|
64
|
-
| `authURL` | `string` | (optional) authentication endpoint for protected resources.
|
|
64
|
+
| `authURL` | `string` | (optional) authentication endpoint for protected resources. |
|
|
65
65
|
| `axiosInstance` | `AxiosInstance` | (optional) Axios instance which will be used for authenticated requests. Defaults to the global Axios |
|
|
66
66
|
| `baseURL` | `string` | base URL of protected resources |
|
|
67
67
|
| `component` | `React.ComponentType` | component to wrap |
|
|
@@ -74,19 +74,21 @@ const App = () => {
|
|
|
74
74
|
|
|
75
75
|
Use `authAdapter` to select the authentication scheme. One of,
|
|
76
76
|
|
|
77
|
-
| Value | Description
|
|
78
|
-
| :----------- |
|
|
79
|
-
| "bearer" | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. |
|
|
80
|
-
| "token" | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. |
|
|
81
|
-
|
|
|
77
|
+
| Value | Description |
|
|
78
|
+
| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
79
|
+
| "bearer" | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. Uses BearerTokenAuth adapter. |
|
|
80
|
+
| "token" | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. Uses TokenServerAuth adapter. |
|
|
81
|
+
| `(context: WithMicroserviceContext) => AuthAdapter` | Custom authentication uses the adapter returned by a function to decorate requests. |
|
|
82
|
+
|
|
83
|
+
See [Authentication Adapters](#authentication-adapters) for more information.
|
|
82
84
|
|
|
83
85
|
#### authUrl
|
|
84
86
|
|
|
85
87
|
The authentication endpoint for protected resources.
|
|
86
88
|
|
|
87
|
-
- For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers.
|
|
89
|
+
- For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers. Defaults to `${baseURL}/bff/silent-login`.
|
|
88
90
|
|
|
89
|
-
- For **Token server** authentication, this the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
|
|
91
|
+
- For **Token server** authentication, this is the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
|
|
90
92
|
|
|
91
93
|
#### preAuthenticate{#pre-authenticate}
|
|
92
94
|
|
|
@@ -136,6 +138,63 @@ const Component = () => {
|
|
|
136
138
|
}
|
|
137
139
|
```
|
|
138
140
|
|
|
141
|
+
### Authentication Adapters{#authentication-adapters}
|
|
142
|
+
|
|
143
|
+
`withMicroservice` uses authentication adapters in order to perform authentication in different ways depending on your needs.
|
|
144
|
+
|
|
145
|
+
#### BearerTokenAuth
|
|
146
|
+
|
|
147
|
+
The default adapter is the `BearerTokenAuth` adapter. When authentication occurs, a request is sent to the `authURL` in order to retrieve a token. Then any requests made using the `baseURL` will add the `Authorization: Bearer ...` header with the stored token.
|
|
148
|
+
|
|
149
|
+
`BearerTokenAuth` can be used by setting `authAdapter` to `'bearer'`.
|
|
150
|
+
|
|
151
|
+
```tsx
|
|
152
|
+
const App = withMicroservice({
|
|
153
|
+
authAdapter: 'bearer',
|
|
154
|
+
baseURL: '/api',
|
|
155
|
+
component: UnwrappedApp,
|
|
156
|
+
});
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
#### TokenServerAuth{#token-server-auth}
|
|
160
|
+
|
|
161
|
+
The `TokenServerAuth` adapter allows you to authenticate with a backend that is using the `ServiceTitan.Ium.Bff` NuGet package ([see TokenServer documentation for details](/docs/projects/ium/tokenserver-new-app-integration/)).
|
|
162
|
+
|
|
163
|
+
This adapter takes care of the silent login portion of the authentication process, setting the application session cookie when your component mounts. For more information about silent login, [view the documentation here](/docs/projects/ium/mfe-silent-login/).
|
|
164
|
+
|
|
165
|
+
If authentication fails (likely because the user is not logged in), the page is reloaded. You can customize this behavior by passing an `onError` function in `TokenServerAuth` options (see below).
|
|
166
|
+
|
|
167
|
+
`TokenServerAuth` can be used by setting `authAdapter` to `'token'`, or to a function that returns a new `TokenServerAuth` instance. Adapter specific options can be passed as the second parameter.
|
|
168
|
+
|
|
169
|
+
```tsx title="Default adapter"
|
|
170
|
+
const App = withMicroservice({
|
|
171
|
+
authAdapter: 'token',
|
|
172
|
+
baseURL: '/api',
|
|
173
|
+
component: UnwrappedApp,
|
|
174
|
+
});
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
```tsx title="Custom adapter"
|
|
178
|
+
const options: TokenServerAuthOptions = {
|
|
179
|
+
authInfoURL: '/custom/authinfo',
|
|
180
|
+
onError: (defaultErrorHandler) => {
|
|
181
|
+
console.error('There was an error');
|
|
182
|
+
defaultErrorHandler();
|
|
183
|
+
},
|
|
184
|
+
};
|
|
185
|
+
const App = withMicroservice({
|
|
186
|
+
authAdapter: context => new TokenServerAuth(context, options),
|
|
187
|
+
baseURL: '/api',
|
|
188
|
+
component: UnwrappedApp,
|
|
189
|
+
});
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
##### TokenServerAuthOptions
|
|
193
|
+
| Name | Type | Description |
|
|
194
|
+
| :------------ | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
195
|
+
| `authInfoURL` | `string` | (optional) URL to fetch authentication parameters from. Defaults to `'/bff/authinfo'`. |
|
|
196
|
+
| `onError` | `(defaultErrorHandler: () => void) => void;` | (optional) Callback to call when an error occurs during authentication. Defaults to reloading the page a maximum of 1 time. First parameter is a function to call the default error handler. |
|
|
197
|
+
|
|
139
198
|
### Authorization
|
|
140
199
|
|
|
141
200
|
`withMicroservice` currently only assists with performing authentication for requests of protected resources. There are currently no plans to implement authorization until we see concrete Token Server usage examples by product teams. If you find that having any sort of implementation for authorization would be helpful, especially in regards to Token Server implementation, please bring any ideas or discussions to the Frontend Platform team's attention so that we can create a platform solution.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@servicetitan/docs-uikit",
|
|
3
|
-
"version": "28.
|
|
3
|
+
"version": "28.5.0",
|
|
4
4
|
"description": "",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -16,5 +16,5 @@
|
|
|
16
16
|
"cli": {
|
|
17
17
|
"webpack": false
|
|
18
18
|
},
|
|
19
|
-
"gitHead": "
|
|
19
|
+
"gitHead": "580ace3d4bce0472e985b1d4eb5e98e0be625f1d"
|
|
20
20
|
}
|