@servicetitan/docs-uikit 28.3.3 → 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 +80 -18
- package/package.json +2 -2
package/docs/ajax-handlers.mdx
CHANGED
|
@@ -58,36 +58,39 @@ const App = () => {
|
|
|
58
58
|
|
|
59
59
|
`withMicroservice` accepts an object with the following properties:
|
|
60
60
|
|
|
61
|
-
| Name
|
|
62
|
-
|
|
|
63
|
-
| `authAdapter`
|
|
64
|
-
| `authURL`
|
|
65
|
-
| `axiosInstance`
|
|
66
|
-
| `baseURL`
|
|
67
|
-
| `component`
|
|
68
|
-
| `extraHeaders`
|
|
69
|
-
| `preAuthenticate`
|
|
70
|
-
| `
|
|
61
|
+
| Name | Type | Description |
|
|
62
|
+
| :------------------------ | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
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. |
|
|
65
|
+
| `axiosInstance` | `AxiosInstance` | (optional) Axios instance which will be used for authenticated requests. Defaults to the global Axios |
|
|
66
|
+
| `baseURL` | `string` | base URL of protected resources |
|
|
67
|
+
| `component` | `React.ComponentType` | component to wrap |
|
|
68
|
+
| `extraHeaders` | `Record<string, any>` | (optional) extra headers to add to requests |
|
|
69
|
+
| `preAuthenticate` | `boolean` | (optional) whether to authenticate immediately or wait for the first request. Defaults to `false`. Value is ignored for Token Server authentication ([see below](#pre-authenticate)). |
|
|
70
|
+
| `preAuthenticateCallback` | `(error?: any) => void` | (optional) callback to call after pre-authentication succeeds or fails. If pre-authentication fails, the error is passed to the first parameter of the callback. |
|
|
71
|
+
| `tokens` | `Symbol[]` | (optional) symbols to use to provide `baseURL` to autogenerated API services and child components |
|
|
71
72
|
|
|
72
73
|
#### authAdapter{#auth-adapter}
|
|
73
74
|
|
|
74
75
|
Use `authAdapter` to select the authentication scheme. One of,
|
|
75
76
|
|
|
76
|
-
| Value | Description
|
|
77
|
-
| :----------- |
|
|
78
|
-
| "bearer" | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. |
|
|
79
|
-
| "token" | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. |
|
|
80
|
-
|
|
|
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.
|
|
81
84
|
|
|
82
85
|
#### authUrl
|
|
83
86
|
|
|
84
87
|
The authentication endpoint for protected resources.
|
|
85
88
|
|
|
86
|
-
- 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`.
|
|
87
90
|
|
|
88
|
-
- 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`.
|
|
89
92
|
|
|
90
|
-
#### preAuthenticate
|
|
93
|
+
#### preAuthenticate{#pre-authenticate}
|
|
91
94
|
|
|
92
95
|
Controls when authentication happens:
|
|
93
96
|
|
|
@@ -96,6 +99,8 @@ Controls when authentication happens:
|
|
|
96
99
|
| `false` | Wait for the first request to a protected resource. This is the default value. |
|
|
97
100
|
| `true` | Authenticate immediately after the component is loaded |
|
|
98
101
|
|
|
102
|
+
When using Token Server authentication, authentication is always performed after the component is loaded and this value is ignored.
|
|
103
|
+
|
|
99
104
|
#### tokens
|
|
100
105
|
|
|
101
106
|
The main purpose of `tokens` is to [provide](./react-ioc#provide) the `baseURL` to autogenerated API services.
|
|
@@ -133,6 +138,63 @@ const Component = () => {
|
|
|
133
138
|
}
|
|
134
139
|
```
|
|
135
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
|
+
|
|
136
198
|
### Authorization
|
|
137
199
|
|
|
138
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
|
}
|