0
# Authentication
1

2
Material UI-styled authentication components for login, logout, and user management in react-admin applications.
3

4
## Capabilities
5

6
### Login Component
7

8
Main login page component with Material UI styling and customizable background.
9

10
```typescript { .api }
11
/**
12
 * Main login page component with Material UI styling
13
 * @param props - Login page configuration props
14
 * @returns Complete login page with form and styling
15
 */
16
function Login(props: LoginProps): ReactElement;
17

18
interface LoginProps extends HtmlHTMLAttributes<HTMLDivElement> {
19
  /** Background image URL for login page */
20
  backgroundImage?: string;
21
  /** Custom login form component or any content */
22
  children?: ReactNode;
23
  /** CSS class name for styling */
24
  className?: string;
25
  /** Material UI sx prop for styling */
26
  sx?: SxProps;
27
}
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import { Login } from "ra-ui-materialui";
34

35
// Basic login page
36
const MyLogin = () => <Login />;
37

38
// Custom login with background
39
const CustomLogin = () => (
40
  <Login 
41
    backgroundImage="/admin-background.jpg"
42
    theme={nanoDarkTheme}
43
  />
44
);
45
```
46

47
### LoginForm Component
48

49
Login form component with username/password fields and Material UI validation.
50

51
```typescript { .api }
52
/**
53
 * Login form component with username/password fields
54
 * @param props - Login form configuration props
55
 * @returns Form component with validation and submission
56
 */
57
function LoginForm(props: LoginFormProps): ReactElement;
58

59
interface LoginFormProps {
60
  /** Redirect path after successful login */
61
  redirectTo?: string;
62
  /** Custom submit button component */
63
  submitButton?: ReactElement;
64
  /** Whether to validate on blur */
65
  validateOnBlur?: boolean;
66
}
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
import { LoginForm } from "ra-ui-materialui";
73

74
// Basic login form
75
const MyLoginForm = () => <LoginForm />;
76

77
// Custom login form with redirect
78
const CustomLoginForm = () => (
79
  <LoginForm 
80
    redirectTo="/dashboard"
81
    validateOnBlur={true}
82
  />
83
);
84
```
85

86
### Logout Component
87

88
Logout button component with confirmation and customizable styling.
89

90
```typescript { .api }
91
/**
92
 * Logout button component with confirmation
93
 * @param props - Logout button configuration props
94
 * @returns Logout button with confirmation dialog
95
 */
96
function Logout(props: LogoutProps): ReactElement;
97

98
interface LogoutProps {
99
  /** Button label text */
100
  label?: string;
101
  /** Button icon component */
102
  icon?: ReactElement;
103
  /** Redirect path after logout */
104
  redirectTo?: string;
105
  /** Click handler */
106
  onClick?: () => void;
107
  /** Button className */
108
  className?: string;
109
}
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import { Logout } from "ra-ui-materialui";
116
import { ExitToApp } from "@mui/icons-material";
117

118
// Basic logout button
119
const MyLogout = () => <Logout />;
120

121
// Custom logout with icon
122
const CustomLogout = () => (
123
  <Logout 
124
    label="Sign Out"
125
    icon={<ExitToApp />}
126
    redirectTo="/login"
127
  />
128
);
129
```
130

131
### UserMenu Component
132

133
User menu dropdown component for authenticated users with profile and logout options.
134

135
```typescript { .api }
136
/**
137
 * User menu dropdown component for authenticated users
138
 * @param props - User menu configuration props
139
 * @returns Dropdown menu with user options
140
 */
141
function UserMenu(props: UserMenuProps): ReactElement;
142

143
interface UserMenuProps {
144
  /** Custom logout component */
145
  logout?: ReactElement;
146
  /** Custom profile menu component */
147
  profileMenu?: ReactElement;
148
  /** User menu icon */
149
  icon?: ReactElement;
150
  /** Menu label */
151
  label?: string;
152
}
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import { UserMenu, Logout } from "ra-ui-materialui";
159
import { AccountCircle } from "@mui/icons-material";
160

161
// Basic user menu
162
const MyUserMenu = () => <UserMenu />;
163

164
// Custom user menu with components
165
const CustomUserMenu = () => (
166
  <UserMenu 
167
    icon={<AccountCircle />}
168
    logout={<Logout label="Log Out" />}
169
    label="Profile"
170
  />
171
);
172
```
173

174
### AuthCallback Component
175

176
Authentication callback page for handling external authentication service responses (e.g. OAuth).
177

178
```typescript { .api }
179
/**
180
 * Authentication callback page for external auth services
181
 * @returns Callback handling component with loading or error state
182
 */
183
function AuthCallback(): ReactElement;
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
import { AuthCallback } from "ra-ui-materialui";
190

191
// Set as auth callback page in Admin
192
const App = () => (
193
  <Admin authCallbackPage={AuthCallback} authProvider={authProvider}>
194
    {/* admin content */}
195
  </Admin>
196
);
197
```
198

199
### AuthError Component
200

201
Error page component for displaying authentication errors with customizable message and styling.
202

203
```typescript { .api }
204
/**
205
 * Authentication error page component
206
 * @param props - Error page configuration props
207
 * @returns Error page with message and login link
208
 */
209
function AuthError(props: AuthErrorProps): ReactElement;
210

211
interface AuthErrorProps {
212
  /** CSS class name for styling */
213
  className?: string;
214
  /** Error page title (translation key or text) */
215
  title?: string;
216
  /** Error message (translation key or text) */
217
  message?: string;
218
  /** Material UI sx prop for styling */
219
  sx?: SxProps;
220
}
221
```
222

223
**Usage Examples:**
224

225
```typescript
226
import { AuthError } from "ra-ui-materialui";
227

228
// Basic auth error page
229
const MyAuthError = () => <AuthError />;
230

231
// Custom auth error with message
232
const CustomAuthError = () => (
233
  <AuthError 
234
    title="Authentication Failed"
235
    message="Invalid credentials. Please try again."
236
  />
237
);
238
```
239

240
## Authentication Hooks
241

242
### User Identity and Permissions
243

244
Hooks for accessing user authentication state and permissions.
245

246
```typescript { .api }
247
/**
248
 * Hook for accessing current user identity information
249
 * @returns User identity object with loading and error states
250
 */
251
function useGetIdentity(): {
252
  data: UserIdentity | undefined;
253
  error: any;
254
  loading: boolean;
255
  refetch: () => void;
256
};
257

258
/**
259
 * Hook for accessing user permissions
260
 * @returns User permissions with loading and error states
261
 */
262
function usePermissions(): {
263
  permissions: any;
264
  error: any;
265
  loading: boolean;
266
};
267

268
/**
269
 * Hook for checking authentication status
270
 * @returns Authentication state with loading and error information
271
 */
272
function useAuthState(): {
273
  loading: boolean;
274
  loaded: boolean;
275
  authenticated: boolean | undefined;
276
  error?: any;
277
};
278
```
279

280
**Usage Examples:**
281

282
```typescript
283
import { useGetIdentity, usePermissions } from "ra-ui-materialui";
284

285
const UserProfile = () => {
286
  const { data: identity, loading } = useGetIdentity();
287
  const { permissions } = usePermissions();
288
  
289
  if (loading) return <div>Loading...</div>;
290
  
291
  return (
292
    <div>
293
      <h2>Welcome {identity?.fullName}</h2>
294
      <p>Role: {permissions?.role}</p>
295
    </div>
296
  );
297
};
298
```
299

300
## Types
301

302
```typescript { .api }
303
interface UserIdentity {
304
  id: string | number;
305
  fullName?: string;
306
  avatar?: string;
307
  email?: string;
308
  [key: string]: any;
309
}
310

311
interface LoginParams {
312
  username: string;
313
  password: string;
314
  [key: string]: any;
315
}
316

317
interface AuthProvider {
318
  login: (params: LoginParams) => Promise<any>;
319
  logout: (params: any) => Promise<void | false | string>;
320
  checkAuth: (params: any) => Promise<void>;
321
  checkError: (error: any) => Promise<void>;
322
  getIdentity: () => Promise<UserIdentity>;
323
  getPermissions: (params: any) => Promise<any>;
324
}
325
```