Authentication and Device Management

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.

Enabling Authentication

To enable authentication in your device farm, you need to pass the --plugin-device-farm-enable-authentication flag while starting the Appium server:

appium --use-plugin=device-farm --plugin-device-farm-enable-authentication

When authentication is enabled: - All endpoints will be secured - Access requires valid credentials - Device access is controlled through user roles and team assignments

Authentication Disabled (Default Behavior)

If the --plugin-device-farm-enable-authentication flag is not passed, the device farm will operate in its default mode:

All endpoints are publicly accessible without authentication
No user roles or permissions are enforced
All devices are accessible to anyone who can reach the device farm
Node registration to hub doesn't require authentication credentials
No user management or team assignments are available

Default Mode

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.

Default Credentials

Before installing the device farm plugin, you can set default admin credentials using environment variables:

export DEFAULT_ADMIN_USERNAME=your_admin_username
export DEFAULT_ADMIN_PASSWORD=your_admin_password

If not set, the default credentials are: - Username: admin - Password: admin

Security Note

It's highly recommended to change the default credentials after your first login.

User Roles

The device farm supports two user roles:

Admin

Create and manage users
Create and manage teams
Manage all devices
Access all features
Generate and manage API tokens

User

Login to the system
Access devices based on team permissions
Generate personal API tokens
Change their password

Node Authentication

When connecting a node to an authenticated hub, you need to provide authentication credentials:

appium --use-plugin=device-farm --plugin-device-farm-hub=<hub-url> \
       --plugin-device-farm-access-key=<access-key> \
       --plugin-device-farm-token=<token>

Getting Access Key and Token

Log in to the device farm dashboard
Click on your profile name in the header
Navigate to the "API Tokens" tab
Click "Generate Token"
Enter a token name and optional expiration date
Click "Create"

The access key will be displayed above the API tokens table. Use both the access key and token when registering nodes.

Automation Authentication

For automated testing, include authentication credentials in your WebDriver capabilities:

const capabilities = {
  // ... other capabilities ...
  'df:accesskey': 'your-access-key',
  'df:token': 'your-token'
};

Device Management

Device Administration

Admin users can: - View all devices in the hub network - Edit device names and tags - Flag devices for maintenance - Exclude devices from the pool - Assign devices to teams

Device Persistence

Device information is persisted in the database, including: - Device names - Tags - Status - Team assignments - Maintenance flags

Device Access Control

Devices can be assigned to specific teams
Users can only access devices assigned to their team
Admins can override team assignments
Maintenance flags prevent device access during maintenance

Best Practices

Security
Change default credentials immediately
Use strong passwords
Regularly rotate API tokens
Set appropriate token expiration dates
Device Management
Use meaningful device names
Tag devices appropriately
Flag devices for maintenance when needed
Regularly review team assignments
Node Configuration
Store node credentials securely
Use environment variables for sensitive data
Monitor node connection status
Implement proper error handling for authentication failures

Securing Logs

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:

Users attempt to log in (credentials are logged)
Nodes register with the hub (API tokens and access keys are logged)
Automation sessions are created (authentication details are logged)

Preventing Credential Exposure in Logs

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:

[
  {
    "pattern": "\"df:jwt\":\\s*\"([^\"\n]+)\"",
    "flags": "i",
    "replacer": "**JWT**"
  },
  {
    "pattern": "\"df:accesskey\":\\s*\"([^\"\n]+)\"",
    "flags": "i",
    "replacer": "**ACCESS_KEY**"
  },
  {
    "pattern": "\"df:token\":\\s*\"([^\"\n]+)\"",
    "flags": "i",
    "replacer": "**TOKEN**"
  },
  {
    "pattern": "\"username\":\\s*\"([^\"\n]+)\"",
    "flags": "i",
    "replacer": "**USERNAME**"
  },
  {
    "pattern": "\"password\":\\s*\"([^\"\n]+)\"",
    "flags": "i",
    "replacer": "**PASSWORD**"
  },
  {
    "pattern": "\"accesskey\":\\s*\"([^\"\n]+)\"",
    "flags": "i",
    "replacer": "**ACCESS_KEY**"
  },
  {
    "pattern": "\"token\":\\s*\"([^\"\n]+)\"",
    "flags": "i",
    "replacer": "**TOKEN**"
  }
]

Then, when starting the Appium server (both hub and node), pass the log filter configuration:

appium --use-plugin=device-farm --log-filter=/path/to/log-filter.json

This configuration will: - Mask JWT tokens - Mask access keys - Mask API tokens - Mask usernames and passwords - Replace sensitive information with placeholder text

Important

Always use the log filter when running the device farm in production environments to prevent credential exposure in logs.

Log Filter Location

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.

Troubleshooting

Upgrade and Installation Issues

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:

appium plugin run device-farm reset
appium plugin run device-farm setup

These commands will: 1. Reset the device farm configuration and database 2. Reinitialize the device farm with fresh settings 3. Reinstall any required dependencies

Data Loss Warning

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.