Skip to content

Commit 4e35bed

Browse files
sudharsan-selvarajsudharsan-selvaraj
authored
fix: update documentations for authentication module (#1673)
1 parent 666be6d commit 4e35bed

18 files changed

+300
-2
lines changed

‎dashboard-frontend

‎documentation/docs/assets/images/authentication/api-token-generate.png

57.3 KB
Loading

‎documentation/docs/assets/images/authentication/api-token.png

45.8 KB
Loading

‎documentation/docs/assets/images/authentication/device-management-2.png

212 KB
Loading

‎documentation/docs/assets/images/authentication/device-management.png

118 KB
Loading

‎documentation/docs/assets/images/authentication/login-screen.png

307 KB
Loading

‎documentation/docs/assets/images/authentication/manage-team-device.png

129 KB
Loading

‎documentation/docs/assets/images/authentication/manage-team-user-1.png

60.5 KB
Loading

‎documentation/docs/assets/images/authentication/manage-team-user-2.png

105 KB
Loading

‎documentation/docs/assets/images/authentication/menu-items.png

98.9 KB
Loading

‎documentation/docs/assets/images/authentication/reset-password.png

40.4 KB
Loading

‎documentation/docs/assets/images/authentication/servers.png

201 KB
Loading

‎documentation/docs/assets/images/authentication/teams.png

53.8 KB
Loading

‎documentation/docs/assets/images/authentication/users.png

70.3 KB
Loading

‎documentation/docs/authentication.md

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# Authentication and Device Management
2+
3+
This section covers the authentication and device management features of Appium Device Farm. These features help secure your device farm and provide better control over device access and management. This feature is available with version 10.0.0 and above.
4+
5+
## Enabling Authentication
6+
7+
To enable authentication in your device farm, you need to pass the `--plugin-device-farm-enable-authentication` flag while starting the Appium server:
8+
9+
```bash
10+
appium --use-plugin=device-farm --plugin-device-farm-enable-authentication
11+
```
12+
13+
When authentication is enabled:
14+
- All endpoints will be secured
15+
- Access requires valid credentials
16+
- Device access is controlled through user roles and team assignments
17+
18+
<div style="display: flex; justify-content: center; margin: 20px 0;">
19+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/login-screen.png" alt="Login Screen" style="width: 80%; max-width: 1200px;">
20+
</div>
21+
22+
## Authentication Disabled (Default Behavior)
23+
24+
If the `--plugin-device-farm-enable-authentication` flag is not passed, the device farm will operate in its default mode:
25+
26+
- All endpoints are publicly accessible without authentication
27+
- No user roles or permissions are enforced
28+
- All devices are accessible to anyone who can reach the device farm
29+
- Node registration to hub doesn't require authentication credentials
30+
- No user management or team assignments are available
31+
32+
!!! note "Default Mode"
33+
The default mode is designed for development and testing environments where security is not a primary concern. For production environments, it's recommended to enable authentication.
34+
35+
## Default Credentials
36+
37+
Before installing the device farm plugin, you can set default admin credentials using environment variables:
38+
39+
```bash
40+
export DEFAULT_ADMIN_USERNAME=your_admin_username
41+
export DEFAULT_ADMIN_PASSWORD=your_admin_password
42+
```
43+
44+
If not set, the default credentials are:
45+
- Username: `admin`
46+
- Password: `admin`
47+
48+
!!! warning "Security Note"
49+
It's highly recommended to change the default credentials after your first login.
50+
51+
<div style="display: flex; justify-content: center; margin: 20px 0;">
52+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/reset-password.png" alt="Reset Password" style="width: 70%; max-width: 1400px;">
53+
</div>
54+
55+
## User Roles
56+
57+
The device farm supports two user roles:
58+
59+
### Admin
60+
- Create and manage users
61+
- Create and manage teams
62+
- Manage all devices
63+
- Access all features
64+
- Generate and manage API tokens
65+
66+
<div style="display: flex; justify-content: center; margin: 20px 0;">
67+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/users.png" alt="User Management" style="width: 0%; max-width: 1400px;">
68+
</div>
69+
<div style="display: flex; justify-content: center; margin: 20px 0;">
70+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/teams.png" alt="Team Management" style="width: 70%; max-width: 1400px;">
71+
</div>
72+
73+
### User
74+
- Login to the system
75+
- Access devices based on team permissions
76+
- Generate personal API tokens
77+
- Change their password
78+
79+
<div style="display: flex; justify-content: center; margin: 20px 0;">
80+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/menu-items.png" alt="Menu Items" style="width: 70%; max-width: 900px;">
81+
</div>
82+
83+
## Node Authentication
84+
85+
When connecting a node to an authenticated hub, you need to provide authentication credentials:
86+
87+
```bash
88+
appium --use-plugin=device-farm --plugin-device-farm-hub=<hub-url> \
89+
--plugin-device-farm-access-key=<access-key> \
90+
--plugin-device-farm-token=<token>
91+
```
92+
93+
<div style="display: flex; justify-content: center; margin: 20px 0;">
94+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/servers.png" alt="Servers Management" style="width: 90%; max-width: 1400px;">
95+
</div>
96+
97+
### Getting Access Key and Token
98+
99+
1. Log in to the device farm dashboard
100+
2. Click on your profile name in the header
101+
3. Navigate to the "API Tokens" tab
102+
4. Click "Generate Token"
103+
5. Enter a token name and optional expiration date
104+
6. Click "Create"
105+
106+
The access key will be displayed above the API tokens table. Use both the access key and token when registering nodes.
107+
108+
<div style="display: flex; justify-content: center; margin: 20px 0;">
109+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/api-token.png" alt="API Token Management" style="width: 70%; max-width: 1400px;">
110+
</div>
111+
<div style="display: flex; justify-content: center; margin: 20px 0;">
112+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/api-token-generate.png" alt="Generate API Token" style="width: 70%; max-width: 1400px;">
113+
</div>
114+
115+
## Automation Authentication
116+
117+
For automated testing, include authentication credentials in your WebDriver capabilities:
118+
119+
```javascript
120+
const capabilities = {
121+
// ... other capabilities ...
122+
'df:accesskey': 'your-access-key',
123+
'df:token': 'your-token'
124+
};
125+
```
126+
127+
## Device Management
128+
129+
### Device Administration
130+
131+
Admin users can:
132+
- View all devices in the hub network
133+
- Edit device names and tags
134+
- Flag devices for maintenance
135+
- Exclude devices from the pool
136+
- Assign devices to teams
137+
138+
<div style="display: flex; justify-content: center; margin: 20px 0;">
139+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/device-management.png" alt="Device Management" style="width: 70%; max-width: 1400px;">
140+
</div>
141+
<div style="display: flex; justify-content: center; margin: 20px 0;">
142+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/device-management-2.png" alt="Device Management Details" style="width: 70%; max-width: 1400px;">
143+
</div>
144+
145+
### Device Persistence
146+
147+
Device information is persisted in the database, including:
148+
- Device names
149+
- Tags
150+
- Status
151+
- Team assignments
152+
- Maintenance flags
153+
154+
### Device Access Control
155+
156+
- Devices can be assigned to specific teams
157+
- Users can only access devices assigned to their team
158+
- Admins can override team assignments
159+
- Maintenance flags prevent device access during maintenance
160+
161+
<div style="display: flex; justify-content: center; margin: 20px 0;">
162+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/manage-team-device.png" alt="Manage Team Devices" style="width: 70%; max-width: 1400px;">
163+
</div>
164+
<div style="display: flex; justify-content: center; margin: 20px 0;">
165+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/manage-team-user-1.png" alt="Manage Team Users 1" style="width: 70%; max-width: 1400px;">
166+
</div>
167+
168+
<div style="display: flex; justify-content: center; margin: 20px 0;">
169+
<img src="https://raw.githubusercontent.com/AppiumTestDistribution/appium-device-farm/main/documentation/docs/assets/images/authentication/manage-team-user-2.png" alt="Manage Team Users 2" style="width: 80%; max-width: 1000px;">
170+
</div>
171+
172+
## Best Practices
173+
174+
1. **Security**
175+
2. Change default credentials immediately
176+
3. Use strong passwords
177+
4. Regularly rotate API tokens
178+
5. Set appropriate token expiration dates
179+
6. **Device Management**
180+
7. Use meaningful device names
181+
8. Tag devices appropriately
182+
9. Flag devices for maintenance when needed
183+
10. Regularly review team assignments
184+
11. **Node Configuration**
185+
12. Store node credentials securely
186+
13. Use environment variables for sensitive data
187+
14. Monitor node connection status
188+
15. Implement proper error handling for authentication failures
189+
190+
## Securing Logs
191+
192+
Since the device farm plugin is part of the Appium ecosystem, logging is managed by Appium. By default, Appium logs all incoming requests along with their request bodies. This can be problematic when:
193+
194+
- Users attempt to log in (credentials are logged)
195+
- Nodes register with the hub (API tokens and access keys are logged)
196+
- Automation sessions are created (authentication details are logged)
197+
198+
### Preventing Credential Exposure in Logs
199+
200+
To prevent sensitive information from being logged, you can use Appium's log filtering feature. Create a JSON file (e.g., `log-filter.json`) with the following content:
201+
202+
```json
203+
[
204+
{
205+
"pattern": "\"df:jwt\":\\s*\"([^\"\n]+)\"",
206+
"flags": "i",
207+
"replacer": "**JWT**"
208+
},
209+
{
210+
"pattern": "\"df:accesskey\":\\s*\"([^\"\n]+)\"",
211+
"flags": "i",
212+
"replacer": "**ACCESS_KEY**"
213+
},
214+
{
215+
"pattern": "\"df:token\":\\s*\"([^\"\n]+)\"",
216+
"flags": "i",
217+
"replacer": "**TOKEN**"
218+
},
219+
{
220+
"pattern": "\"username\":\\s*\"([^\"\n]+)\"",
221+
"flags": "i",
222+
"replacer": "**USERNAME**"
223+
},
224+
{
225+
"pattern": "\"password\":\\s*\"([^\"\n]+)\"",
226+
"flags": "i",
227+
"replacer": "**PASSWORD**"
228+
},
229+
{
230+
"pattern": "\"accesskey\":\\s*\"([^\"\n]+)\"",
231+
"flags": "i",
232+
"replacer": "**ACCESS_KEY**"
233+
},
234+
{
235+
"pattern": "\"token\":\\s*\"([^\"\n]+)\"",
236+
"flags": "i",
237+
"replacer": "**TOKEN**"
238+
}
239+
]
240+
```
241+
242+
Then, when starting the Appium server (both hub and node), pass the log filter configuration:
243+
244+
```bash
245+
appium --use-plugin=device-farm --log-filter=/path/to/log-filter.json
246+
```
247+
248+
This configuration will:
249+
- Mask JWT tokens
250+
- Mask access keys
251+
- Mask API tokens
252+
- Mask usernames and passwords
253+
- Replace sensitive information with placeholder text
254+
255+
!!! warning "Important"
256+
Always use the log filter when running the device farm in production environments to prevent credential exposure in logs.
257+
258+
!!! note "Log Filter Location"
259+
Store the log filter configuration file in a secure location and ensure it's included in your deployment process for both hub and node instances.
260+
261+
## Troubleshooting
262+
263+
### Upgrade and Installation Issues
264+
265+
If you encounter any errors while upgrading the device farm from version 9.x to 10.x or experience issues with Prisma installation, execute the following commands to reset and reinitialize the device farm:
266+
267+
```bash
268+
appium plugin run device-farm reset
269+
appium plugin run device-farm setup
270+
```
271+
272+
These commands will:
273+
1. Reset the device farm configuration and database
274+
2. Reinitialize the device farm with fresh settings
275+
3. Reinstall any required dependencies
276+
277+
!!! warning "Data Loss Warning"
278+
The reset command will clear all existing data including users, teams, and device assignments. Make sure to backup any important data before running these commands.

‎documentation/docs/server-args.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ These arguments are set when you launch the Appium server with device-farm plugi
66

77
| Argument | Required | Description | Default | Options |
88
|--------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
9+
| `--plugin-device-farm-enable-authentication` | No | Enables authentication for the device farm. When enabled, all endpoints will be secured and require valid credentials. | `false` | `true/false` |
10+
| `--plugin-device-farm-access-key` | No | Access key for node authentication when connecting to a hub with authentication enabled. Required when hub has authentication enabled. | None | String value |
11+
| `--plugin-device-farm-token` | No | API token for node authentication when connecting to a hub with authentication enabled. Required when hub has authentication enabled. | None | String value |
912
| `--plugin-device-farm-platform` | Yes | Platform to run tests against for parallel execution | None | `both`,`ios`,`android` |
1013
| `--plugin-device-farm-ios-device-type` | No | Types of ios devices to include | `both` | `both`,`simulated`,`real`, For example: If you want to run only against iOS simulator then specify --plugin-device-farm-ios-device-type=simulated |
1114
| `--plugin-device-farm-android-device-type` | No | Types of android devices to include | `both` | `both`,`simulated`,`real`, For example: If you want to run only against android emulator then specify --plugin-device-farm-android-device-type=simulated |
@@ -40,6 +43,22 @@ These arguments are set when you launch the Appium server with device-farm plugi
4043

4144
Above cli arguments can also be set from config.json file Refer [here](https://github.com/AppiumTestDistribution/appium-device-farm/blob/main/sample-config.json)
4245

46+
### Authentication Configuration
47+
48+
When enabling authentication, you can set default admin credentials using environment variables:
49+
50+
```bash
51+
export DEFAULT_ADMIN_USERNAME=your_admin_username
52+
export DEFAULT_ADMIN_PASSWORD=your_admin_password
53+
```
54+
55+
If not set, the default credentials are:
56+
- Username: `admin`
57+
- Password: `admin`
58+
59+
!!! warning "Security Note"
60+
It's highly recommended to change the default credentials after your first login.
61+
4362
### Proxy configuration for axios
4463

4564
If you need to set proxy for remote and cloud execution, appium-device-farm will use the proxy provided and pass that to HttpAgent and HttpsAgent.

‎documentation/mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ extra_css:
4343
nav:
4444
- index.md
4545
- setup.md
46+
- authentication.md
4647
- troubleshooting.md
4748
- cloud.md
4849
- remote-execution.md

‎src/modules

0 commit comments

Comments
 (0)