From 8d4bf5bbd22f0a9680befb53d03fc2d979b4c008 Mon Sep 17 00:00:00 2001
From: Victor Lyuboslavsky <victor@fleetdm.com>
Date: Fri, 13 Jun 2025 15:59:48 -0500
Subject: [PATCH] Updating Android contributor docs. (#29880)

Fixes #26519
---
 .../product-groups/mdm/android-mdm.md         | 41 +++++++++++++++----
 1 file changed, 32 insertions(+), 9 deletions(-)

diff --git a/docs/Contributing/product-groups/mdm/android-mdm.md b/docs/Contributing/product-groups/mdm/android-mdm.md
index 6cad5089ff..ef26efeb72 100644
--- a/docs/Contributing/product-groups/mdm/android-mdm.md
+++ b/docs/Contributing/product-groups/mdm/android-mdm.md
@@ -5,7 +5,13 @@
 - [Google Cloud Pub/Sub API](https://cloud.google.com/pubsub/docs/reference/rest)
 - [Google Cloud console pub/sub topics](https://console.cloud.google.com/cloudpubsub/topic/list)
 
-## Setup an Android MDM environment
+## Using Android MDM for development
+
+By default, Fleet server uses fleetdm.com proxy to access the Google Android Management API. However, the proxy limits each Fleet server URL to 1 Android enterprise. This means that you should turn off Android MDM before wiping your development DB.
+
+You can also setup a local proxy or use the Google API directly.
+
+## Setup a Google project and service account
 
 Create a Google service account with the following Roles
 - Android Management User
@@ -16,23 +22,40 @@ To do so:
 * Follow instructions at https://developers.google.com/android/management/notifications to create pub/sub notifications
 * Troubleshooting: watch the video of Gabe and Victor discussion post-standup: https://us-65885.app.gong.io/call?id=4731209913082368849 (starting at the 12:50 timestamp)
 
-## Configure dev environment
+## Run an Android MDM environment with a local proxy
 
-Using the `credentials.json` of the above account:
-```bash
-export FLEET_DEV_ANDROID_SERVICE_CREDENTIALS=$(cat credentials.json)
+If you're hosting your own Fleet website instance, you need to set the following in `website/config/custom.js`:
+
+```javascript
+  // Android proxy
+  androidEnterpriseProjectId: 'yourProject-123456',
+  androidEnterpriseServiceAccountEmailAddress: 'yourUser@yourProject-123456.iam.gserviceaccount.com',
+  androidEnterpriseServiceAccountPrivateKey: '-----BEGIN PRIVATE KEY-----\nDATA\n-----END PRIVATE KEY-----\n',
 ```
 
-Set the feature flag:
+And also set the following env var for your Fleet server:
+
 ```bash
-export FLEET_DEV_ANDROID_ENABLED=1
+export FLEET_DEV_ANDROID_PROXY_ENDPOINT=https://public.url.of.your.website/api/endpoint/
+```
+
+Then, launch the website and your Fleet server.
+
+## Run an Android MDM environment connected directly to Google
+
+Set the following env vars:
+
+```bash
+export FLEET_DEV_ANDROID_GOOGLE_CLIENT=1
+export FLEET_DEV_ANDROID_GOOGLE_SERVICE_CREDENTIALS=$(cat credentials.json)
 ```
 
 To turn on Android MDM, use a Chrome private window (so that you are not logged in with your "fleetdm.com" address). This is only required to enable Android MDM, you can use a normal window for the rest. In "Settings -> Integrations -> MDM -> Turn On Android -> Connect", use a personal email address (not a "fleetdm.com" one). Select "Sign-up for Android only". Domain name is not important ("test.com" for example). No need to fill anything in the "Data protection officer" and "EU representative" sections, just check the checkbox.
 
 ## Known issues and limitations
 - The Fleet server URL must be public for pub/sub to work properly.
-- The Fleet server URL cannot change -- pub/sub is set up with one URL.
+- The Fleet server URL cannot change -- pub/sub is set up with one URL. See issue [Allow Fleet server URL update when using Android](https://github.com/fleetdm/fleet/issues/29878)
+- Network reliability issues may leave the Android enterprise flow in a broken state. For example, if fleetdm.com proxy creates an Android enteprise but Fleet server goes offline and does not receive the secret key.
 
 ## Architecture diagrams
 
@@ -139,5 +162,5 @@ Android enterprise signup callback is authenticated by a token in the callback U
 
 Getting the Android device enrollment token is authenticated with the Fleet enroll secret.
 
-Pub/sub push callback is authenticated by a `token` query parameter. This token is created by Fleet server. As of March 2025, this token cannot be easily rotated. We could add another level of authentication where the Fleet server would need to check with Google to authenticate the pub/sub message:
+Pub/sub push callback is authenticated by a `token` query parameter. This token is created by Fleet server. As of June 2025, this token cannot be easily rotated. We could add another level of authentication where the Fleet server would need to check with Google to authenticate the pub/sub message:
 - [Authentication for push subscriptions](https://cloud.google.com/pubsub/docs/authenticate-push-subscriptions)