From 396ac631deff9ab6b66734374fbdcf20fba4bf33 Mon Sep 17 00:00:00 2001 From: Thomas Rittson <31796059+eliykat@users.noreply.github.com> Date: Tue, 13 Aug 2024 06:09:10 +1000 Subject: [PATCH 1/3] Add Splunk documentation (#386) --- custom-words.txt | 1 + docs/getting-started/business/_category_.yml | 2 + .../directory-connector/directory-100.ldif | 0 .../directory-connector/directory-20.ldif | 0 .../directory-connector/directory-250.ldif | 0 .../directory-connector/directory-50.ldif | 0 .../directory-connector/directory-500.ldif | 0 .../directory-connector/index.mdx | 0 .../directory-connector/jumpcloud.md | 0 .../directory-connector/mail-hosts.txt | 0 .../directory-connector/open-ldap.md | 0 .../key-connector.mdx | 0 docs/getting-started/business/splunk-app.md | 105 ++++++++++++++++++ .../getting-started/enterprise/_category_.yml | 2 - 14 files changed, 108 insertions(+), 2 deletions(-) create mode 100644 docs/getting-started/business/_category_.yml rename docs/getting-started/{enterprise => business}/directory-connector/directory-100.ldif (100%) rename docs/getting-started/{enterprise => business}/directory-connector/directory-20.ldif (100%) rename docs/getting-started/{enterprise => business}/directory-connector/directory-250.ldif (100%) rename docs/getting-started/{enterprise => business}/directory-connector/directory-50.ldif (100%) rename docs/getting-started/{enterprise => business}/directory-connector/directory-500.ldif (100%) rename docs/getting-started/{enterprise => business}/directory-connector/index.mdx (100%) rename docs/getting-started/{enterprise => business}/directory-connector/jumpcloud.md (100%) rename docs/getting-started/{enterprise => business}/directory-connector/mail-hosts.txt (100%) rename docs/getting-started/{enterprise => business}/directory-connector/open-ldap.md (100%) rename docs/getting-started/{enterprise => business}/key-connector.mdx (100%) create mode 100644 docs/getting-started/business/splunk-app.md delete mode 100644 docs/getting-started/enterprise/_category_.yml diff --git a/custom-words.txt b/custom-words.txt index ff37ef57f..ee7d41839 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -28,6 +28,7 @@ keypair keyserver Kubebuilder LDIF +libmagic LLDB Mailcatcher minio diff --git a/docs/getting-started/business/_category_.yml b/docs/getting-started/business/_category_.yml new file mode 100644 index 000000000..9d85a1ca5 --- /dev/null +++ b/docs/getting-started/business/_category_.yml @@ -0,0 +1,2 @@ +label: "Business apps" +position: 6 diff --git a/docs/getting-started/enterprise/directory-connector/directory-100.ldif b/docs/getting-started/business/directory-connector/directory-100.ldif similarity index 100% rename from docs/getting-started/enterprise/directory-connector/directory-100.ldif rename to docs/getting-started/business/directory-connector/directory-100.ldif diff --git a/docs/getting-started/enterprise/directory-connector/directory-20.ldif b/docs/getting-started/business/directory-connector/directory-20.ldif similarity index 100% rename from docs/getting-started/enterprise/directory-connector/directory-20.ldif rename to docs/getting-started/business/directory-connector/directory-20.ldif diff --git a/docs/getting-started/enterprise/directory-connector/directory-250.ldif b/docs/getting-started/business/directory-connector/directory-250.ldif similarity index 100% rename from docs/getting-started/enterprise/directory-connector/directory-250.ldif rename to docs/getting-started/business/directory-connector/directory-250.ldif diff --git a/docs/getting-started/enterprise/directory-connector/directory-50.ldif b/docs/getting-started/business/directory-connector/directory-50.ldif similarity index 100% rename from docs/getting-started/enterprise/directory-connector/directory-50.ldif rename to docs/getting-started/business/directory-connector/directory-50.ldif diff --git a/docs/getting-started/enterprise/directory-connector/directory-500.ldif b/docs/getting-started/business/directory-connector/directory-500.ldif similarity index 100% rename from docs/getting-started/enterprise/directory-connector/directory-500.ldif rename to docs/getting-started/business/directory-connector/directory-500.ldif diff --git a/docs/getting-started/enterprise/directory-connector/index.mdx b/docs/getting-started/business/directory-connector/index.mdx similarity index 100% rename from docs/getting-started/enterprise/directory-connector/index.mdx rename to docs/getting-started/business/directory-connector/index.mdx diff --git a/docs/getting-started/enterprise/directory-connector/jumpcloud.md b/docs/getting-started/business/directory-connector/jumpcloud.md similarity index 100% rename from docs/getting-started/enterprise/directory-connector/jumpcloud.md rename to docs/getting-started/business/directory-connector/jumpcloud.md diff --git a/docs/getting-started/enterprise/directory-connector/mail-hosts.txt b/docs/getting-started/business/directory-connector/mail-hosts.txt similarity index 100% rename from docs/getting-started/enterprise/directory-connector/mail-hosts.txt rename to docs/getting-started/business/directory-connector/mail-hosts.txt diff --git a/docs/getting-started/enterprise/directory-connector/open-ldap.md b/docs/getting-started/business/directory-connector/open-ldap.md similarity index 100% rename from docs/getting-started/enterprise/directory-connector/open-ldap.md rename to docs/getting-started/business/directory-connector/open-ldap.md diff --git a/docs/getting-started/enterprise/key-connector.mdx b/docs/getting-started/business/key-connector.mdx similarity index 100% rename from docs/getting-started/enterprise/key-connector.mdx rename to docs/getting-started/business/key-connector.mdx diff --git a/docs/getting-started/business/splunk-app.md b/docs/getting-started/business/splunk-app.md new file mode 100644 index 000000000..3f5d42257 --- /dev/null +++ b/docs/getting-started/business/splunk-app.md @@ -0,0 +1,105 @@ +# Splunk app + +The Bitwarden Splunk app fetches event log data from the Bitwarden Public API and makes it available +in Splunk. + +## Requirements + +- Docker. If you're using an Apple Silicon Mac, enable _Docker Desktop_ -> _Settings_ -> _General_ + -> _Use Rosetta for x86_64/amd64 emulation on Apple Silicon_ +- Python 3.7 - 3.10 +- [Poetry][poetry] +- libmagic (macOS only), available via homebrew: `brew install libmagic` +- A Bitwarden Teams or Enterprise organization +- If using a local development server - make sure the Events and EventsProcessor projects are + running and [Event Logging](../server/events.md) is working + +## Set up and configuration + +### Configure your environment + +1. Clone the Github repository: + + ``` + git clone https://github.com/bitwarden/splunk.git + ``` + +2. Navigate to the root of the repository: + + ``` + cd splunk + ``` + +3. Tell poetry to use the required Python version: + + ``` + poetry env use + ``` + + Where `` is the executable for Python. If this is in your PATH variable then you do + not need to specify the full path. e.g. `poetry env use python3.8` + +4. Activate the poetry shell: + + ``` + poetry shell + ``` + +5. Install dependencies: + + ``` + poetry install --with dev + ``` + +### Set up Splunk Enterprise + +1. Run Splunk Enterprise: + + ``` + docker run --rm --platform linux/amd64 --name splunk -d -p 8001:8000 -p 8089:8089 -e SPLUNK_START_ARGS='--accept-license' -e SPLUNK_PASSWORD='password' splunk/splunk:latest + ``` + + Please note this will set the admin password to `password`. This is for development purposes + only. + +2. Confirm that Splunk is running by navigating to http://localhost:8001 + +### Deploy the app + +1. Package the app: + + ``` + ./package.sh + ``` + + This will produce a packaged Splunk app in `output/bitwarden_event_logs.tar.gz` + +2. Deploy the app to Splunk: + + ``` + ./deploy.sh + ``` + + This will restart Splunk and it may take a few seconds to become available again after the script + is finished + +3. (optional) Check the logs for errors or for debugging purposes later: + ``` + docker exec -u splunk -it splunk tail -f /opt/splunk/var/log/splunk/bitwarden_event_logs_beta.log + ``` + +### Configure the app in Splunk + +1. Navigate to the Splunk web app: http://localhost:8001 + +2. Log in with the username `admin` and the password `password` + +3. Click on the _Apps_ -> _Bitwarden Event Logs_ + +4. Complete the setup. Refer to the [Bitwarden Help Center][Bitwarden Splunk SIEM] for more + information about configuration + +You should now see your organization events in _Apps_ -> _Bitwarden Event Logs_ -> _Dashboards_. + +[Bitwarden Splunk SIEM]: https://bitwarden.com/help/splunk-siem/ +[poetry]: https://python-poetry.org/docs/#installation diff --git a/docs/getting-started/enterprise/_category_.yml b/docs/getting-started/enterprise/_category_.yml deleted file mode 100644 index 8e77e7bd4..000000000 --- a/docs/getting-started/enterprise/_category_.yml +++ /dev/null @@ -1,2 +0,0 @@ -label: "Enterprise" -position: 6 From af632ddf8803a5f6c746f6e16a21931182ec7796 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Tue, 13 Aug 2024 13:34:38 -0400 Subject: [PATCH 2/3] [deps]: Update gh minor (#401) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- .github/workflows/scan.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/scan.yml b/.github/workflows/scan.yml index a26ec782a..4e75b766c 100644 --- a/.github/workflows/scan.yml +++ b/.github/workflows/scan.yml @@ -29,7 +29,7 @@ jobs: ref: ${{ github.event.pull_request.head.sha }} - name: Scan with Checkmarx - uses: checkmarx/ast-github-action@4c637b1cb6b6b63637c7b99578c9fceefebbb08d # 2.0.30 + uses: checkmarx/ast-github-action@1fe318de2993222574e6249750ba9000a4e2a6cd # 2.0.33 env: INCREMENTAL: "${{ contains(github.event_name, 'pull_request') && '--sast-incremental' || '' }}" @@ -45,7 +45,7 @@ jobs: --output-path . ${{ env.INCREMENTAL }} - name: Upload Checkmarx results to GitHub - uses: github/codeql-action/upload-sarif@2d790406f505036ef40ecba973cc774a50395aac # v3.25.13 + uses: github/codeql-action/upload-sarif@eb055d739abdc2e8de2e5f4ba1a8b246daa779aa # v3.26.0 with: sarif_file: cx_result.sarif From d1f0edf14cc1e1105ed2e98c51e4660d782686f0 Mon Sep 17 00:00:00 2001 From: Federico Maccaroni Date: Tue, 13 Aug 2024 16:44:49 -0300 Subject: [PATCH 3/3] [PM-7516] Restructure mobile docs for new native apps (#399) * PM-7516 Restructured mobile docs for the new native apps and the legacy NET MAUI docs. * PM-7516 Fix links. * PM-7516 Fixed warnings on NET MAUI docs. * Update docs/architecture/mobile-clients/android/index.md Co-authored-by: Matt Bishop * Update docs/architecture/mobile-clients/net-maui-legacy/index.mdx Co-authored-by: Matt Bishop * Update docs/architecture/mobile-clients/net-maui-legacy/index.mdx Co-authored-by: Matt Bishop * Update docs/architecture/mobile-clients/net-maui-legacy/index.mdx Co-authored-by: Matt Bishop * PM-7516 Improve mobile clients docs based on PR feedback. --------- Co-authored-by: Matt Bishop --- .../mobile-clients/_category_.yml | 2 + .../mobile-clients/android/index.md | 11 ++ docs/architecture/mobile-clients/ios/index.md | 12 ++ .../{ => net-maui-legacy}/index.mdx | 12 +- .../{ => net-maui-legacy}/overview.md | 10 +- .../{ => net-maui-legacy}/watchOS.md | 6 + docs/getting-started/mobile/android/index.md | 174 +---------------- docs/getting-started/mobile/index.md | 93 +-------- docs/getting-started/mobile/ios/index.md | 11 ++ .../android/android-sdk.png | Bin .../mobile/net-maui-legacy/android/index.md | 177 ++++++++++++++++++ .../mobile/net-maui-legacy/index.md | 107 +++++++++++ .../{ => net-maui-legacy}/ios/index.mdx | 8 +- .../ios/new-project-options.png | Bin .../{ => net-maui-legacy}/ios/run-debug.png | Bin .../ios/signing-and-capabilities.png | Bin .../ios/troubleshoot-generic-simulator.png | Bin .../{ => net-maui-legacy}/watchos/index.mdx | 10 +- 18 files changed, 370 insertions(+), 263 deletions(-) create mode 100644 docs/architecture/mobile-clients/_category_.yml create mode 100644 docs/architecture/mobile-clients/android/index.md create mode 100644 docs/architecture/mobile-clients/ios/index.md rename docs/architecture/mobile-clients/{ => net-maui-legacy}/index.mdx (88%) rename docs/architecture/mobile-clients/{ => net-maui-legacy}/overview.md (59%) rename docs/architecture/mobile-clients/{ => net-maui-legacy}/watchOS.md (98%) create mode 100644 docs/getting-started/mobile/ios/index.md rename docs/getting-started/mobile/{ => net-maui-legacy}/android/android-sdk.png (100%) create mode 100644 docs/getting-started/mobile/net-maui-legacy/android/index.md create mode 100644 docs/getting-started/mobile/net-maui-legacy/index.md rename docs/getting-started/mobile/{ => net-maui-legacy}/ios/index.mdx (98%) rename docs/getting-started/mobile/{ => net-maui-legacy}/ios/new-project-options.png (100%) rename docs/getting-started/mobile/{ => net-maui-legacy}/ios/run-debug.png (100%) rename docs/getting-started/mobile/{ => net-maui-legacy}/ios/signing-and-capabilities.png (100%) rename docs/getting-started/mobile/{ => net-maui-legacy}/ios/troubleshoot-generic-simulator.png (100%) rename docs/getting-started/mobile/{ => net-maui-legacy}/watchos/index.mdx (94%) diff --git a/docs/architecture/mobile-clients/_category_.yml b/docs/architecture/mobile-clients/_category_.yml new file mode 100644 index 000000000..ba025eba2 --- /dev/null +++ b/docs/architecture/mobile-clients/_category_.yml @@ -0,0 +1,2 @@ +label: "Mobile Clients Architecture" +position: 2 diff --git a/docs/architecture/mobile-clients/android/index.md b/docs/architecture/mobile-clients/android/index.md new file mode 100644 index 000000000..04165429e --- /dev/null +++ b/docs/architecture/mobile-clients/android/index.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# Android + +Architecture documentation for the Android application as well as its unit tests. + +## Repository + +https://github.com/bitwarden/android diff --git a/docs/architecture/mobile-clients/ios/index.md b/docs/architecture/mobile-clients/ios/index.md new file mode 100644 index 000000000..418196f8d --- /dev/null +++ b/docs/architecture/mobile-clients/ios/index.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 1 +--- + +# iOS + +Architecture documentation for the iOS application with extensions and the watchOS application as +well as their unit and snapshot tests. + +## Repository + +https://github.com/bitwarden/ios diff --git a/docs/architecture/mobile-clients/index.mdx b/docs/architecture/mobile-clients/net-maui-legacy/index.mdx similarity index 88% rename from docs/architecture/mobile-clients/index.mdx rename to docs/architecture/mobile-clients/net-maui-legacy/index.mdx index bef9a6087..ef98de0d2 100644 --- a/docs/architecture/mobile-clients/index.mdx +++ b/docs/architecture/mobile-clients/net-maui-legacy/index.mdx @@ -2,10 +2,16 @@ sidebar_position: 5 --- -# Mobile Clients Architecture +# .NET MAUI (legacy) -The mobile clients are Android, iOS with its extensions and watchOS. They all are located in this -[Git repository](https://github.com/bitwarden/mobile). +:::warning Legacy + +This represents the **legacy** mobile app architecture done in .NET MAUI. + +::: + +The mobile .NET MAUI clients are Android and iOS applications with extensions and watchOS. They are +all located at https://github.com/bitwarden/mobile. Principal structure is a follows: diff --git a/docs/architecture/mobile-clients/overview.md b/docs/architecture/mobile-clients/net-maui-legacy/overview.md similarity index 59% rename from docs/architecture/mobile-clients/overview.md rename to docs/architecture/mobile-clients/net-maui-legacy/overview.md index ded90c744..8a1a21f0b 100644 --- a/docs/architecture/mobile-clients/overview.md +++ b/docs/architecture/mobile-clients/net-maui-legacy/overview.md @@ -4,8 +4,14 @@ sidebar_position: 1 # Overview +:::warning Legacy + +This represents the **legacy** mobile app overview architecture done in .NET MAUI. + +::: + The overall architecture of the mobile applications is pretty similar to the -[web clients](../clients/overview.md) one following a layered architecture: +[web clients](../../clients/overview.md) one following a layered architecture: - State - Services @@ -17,4 +23,4 @@ differs: ## Presentation The presentation layer is implemented using .NET MAUI for the mobile apps, except for the watchOS -one which uses SwiftUI [see ADR](../adr/watchOS-use-swift) +one which uses SwiftUI [see ADR](../../adr/0017-watchOS-use-swift.md) diff --git a/docs/architecture/mobile-clients/watchOS.md b/docs/architecture/mobile-clients/net-maui-legacy/watchOS.md similarity index 98% rename from docs/architecture/mobile-clients/watchOS.md rename to docs/architecture/mobile-clients/net-maui-legacy/watchOS.md index de3acaf20..79742a961 100644 --- a/docs/architecture/mobile-clients/watchOS.md +++ b/docs/architecture/mobile-clients/net-maui-legacy/watchOS.md @@ -1,5 +1,11 @@ # watchOS +:::warning Legacy + +This represents the **legacy** watchOS app architecture done in .NET MAUI. + +::: + ## Overall architecture The watchOS application is organized as follows: diff --git a/docs/getting-started/mobile/android/index.md b/docs/getting-started/mobile/android/index.md index c2962e02e..2b7354134 100644 --- a/docs/getting-started/mobile/android/index.md +++ b/docs/getting-started/mobile/android/index.md @@ -1,171 +1,11 @@ -# Android - -## Requirements - -Before you start, you should have the recommended [Tools and Libraries](../../tools/index.md) -installed. You will also need to install: - -1. Visual Studio 2022 / VS Code -2. [.NET 8 (latest)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) - - Note: Even if you have an ARM64 based Mac (M1, M2, M3, etc.), you can install all x64 SDKs to - run Android - - On Visual Studio for Mac you may need to turn on the feature for .NET 8 by going to Visual - Studio > Preferences > Preview Features > Use the .NET 8 SDK -3. .NET MAUI Workload - - You can install this by running `dotnet workload install maui` -4. Android SDK 34 - - You can use the SDK manager in [Visual Studio][xamarin-vs], or [Android - Studio][android-studio] to install this - -To make sure you have the Android SDK and Emulator installed: - -1. Open Visual Studio -2. Click Tools > SDK Manager (under the Android subheading) -3. Click the Tools tab -4. Make sure the following items are installed: - - - Android SDK tools (at least one version of the command-line tools) - - Android SDK Platform-Tools - - Android SDK Build Tools (at least one version) - - Android Emulator - -5. Click Apply Changes if you've marked anything for installation - -If you've missed anything, Visual Studio should prompt you anyway. - -## Android Development Setup - -To set up a new virtual Android device for debugging: - -1. Click Tools > Device Manager (under the Android subheading) -2. Click New Device -3. Set up the device you want to emulate - you can just choose the Base Device and leave the - default settings if you're unsure -4. Visual Studio will then download the image for that device. The download progress is shown in - the progress in the Android Device Manager dialog. -5. Once this has completed, the emulated Android device will be available as a build target under - App > Debug > (name of device) - -### ARM64 Macs - -1. Install and open Android Studio -2. In the top navbar, click on Android Studio > Settings > Appearance & Behavior (tab) > System - Settings > Android SDK -3. In the SDK Platforms tab, ensure the "Show Package Details" checkbox is checked (located in the - bottom-right) -4. Bellow each Android API you'll see several System Images, pick one of the `ARM 64 v8a` and wait - for it to download -5. Go to View > Tool Windows > Device Manager -6. Inside Device Manager, create a device using the previously downloaded system image - -![Android SDK configuration](android-sdk.png) - -## F-Droid - -On `App.csproj` and `Core.csproj` we can now pass `/p:CustomConstants=FDROID` when -building/releasing so that the `FDROID` constant is added to the defined ones at the project level -and we can use that with precompiler directives, e.g.: - -```c# -#if FDROID - // perform operation only for FDROID. -#endif -``` - -## Building - -There are currently a few problems on Visual Studio for Mac for building correctly the projects, so -if you encounter some errors build using the CLI (previously removing bin/obj folders): - -``` -dotnet build -f net8.0-android -c Debug -``` - -## Testing and Debugging - -### Using the Android Emulator - -In order to access `localhost:` resources in the Android Emulator when debugging using Visual -Studio on your Mac natively, you'll need to configure the endpoint addresses using -``\> in order to access `localhost`, which maps the Android proxy by design. +--- +sidebar_position: 1 +--- -[xamarin-vs]: https://learn.microsoft.com/en-us/xamarin/android/get-started/installation/android-sdk -[android-studio]: https://developer.android.com/studio/releases/platforms - -### Using Server Tunneling - -Instead of configuring your device or emulator, you can instead use a -[proxy tunnel to your local server](../../server/tunnel.md) and have your app connect to it -directly. - -### Push Notifications - -The default configuration for the Android app is to register itself to the same environment as -Bitwarden's QA Cloud. This means that if you try to debug the app using the production endpoints you -won't be able to receive Live Sync updates or Passwordless login requests. - - - -So, in order to receive notifications while debugging, you have two options: - -- Use QA Cloud endpoints for the Api and Identity, or -- Use a local server setup where the Api is connected to QA Azure Notification Hub - - - -### Testing Passwordless Locally - -Before you can start testing and debugging passwordless logins, make sure your local server setup is -running correctly ([server setup](../../server/guide.md)). You should also be able to deploy your -Android app to your device or emulator. - -:::note - -Debugging and testing passwordless authentication is limited by -[push notifications](#push-notifications). - -::: - -Testing passwordless notifications: - -1. Start your local server (`Api`, `Identity`, `Notifications`) -2. Make sure your mobile device can [connect to your local server](#using-server-tunneling) -3. [Start the web client](../../clients/web-vault/index.mdx), as you will need it to make login - requests -4. Deploy the Android app to your device or emulator -5. After deployment, open the app, login to your QA account and activate passwordless login requests - in settings -6. Open the web vault using your preferred browser (ex: http://localhost:8080) -7. Enter the email address of an account that has previously authenticated on that device (i.e. is a - "known device") and click Continue. When presented with the login options, click click Login with - Device. -8. Check mobile device for the notification - - - -## AndroidX Credentials - -Currently, the -[androidx.credentials](https://developer.android.com/jetpack/androidx/releases/credentials) official -binding has some bugs and we cannot use it yet. Because of this, we made a binding ourselves which -is located in here: -[Xamarin.AndroidX.Credentials](https://github.com/bitwarden/xamarin.androidx.credentials). - -As of today, we are using version 1.2.0. - -In the projects, the package is added as a local NuGet package located in -`lib/android/Xamarin.AndroidX.Credentials` and this source is already configured in the -`nuget.config` file. - -In the case a change is needed on the binding, create a new local NuGet package and replace it in -the aforementioned source. - -:::warning +# Android -Do not add the project to the solution and as a project reference to the `App.csproj` / -`Core.csproj` this will strangely make the iOS app crash on start because of solution configuration. -Even though we couldn't find the root cause, this is the effect caused by this action. +How to get started with the Android Bitwarden project in Kotlin. -::: +## Repository - +https://github.com/bitwarden/android diff --git a/docs/getting-started/mobile/index.md b/docs/getting-started/mobile/index.md index 1313de450..55ec85714 100644 --- a/docs/getting-started/mobile/index.md +++ b/docs/getting-started/mobile/index.md @@ -4,98 +4,15 @@ sidebar_position: 4 # Mobile -## Configure Git blame - -We recommend that you configure git to ignore the Prettier revision: - -```bash -git config blame.ignoreRevsFile .git-blame-ignore-revs -``` - ## Android Development -See the [Android Mobile app](./android/index.md) page to set up an Android development environment. +See the [Android Mobile app](./android/index.md) page to set up a Kotlin development environment. ## iOS Development - - -See the [iOS Mobile app](./ios/index.mdx) page to set up an iOS development environment. - - - - - -Unfortunately, iOS development requires provisioning profiles and other capabilities only available -to internal team members. We do not have any documentation for community developers at this time. - - - -## watchOS Development - - - -See the [watchOS app](./watchos) page to set up an watchOS development environment. - - - - - -Unfortunately, watchOS development requires provisioning profiles and other capabilities only -available to internal team members. We do not have any documentation for community developers at -this time. - - - -## Unit tests - -:::info TL;DR; - -In order to run unit tests add the argument `/p:CustomConstants=UT` on the `dotnet` command for -building/running. To work on Unit testing or use a Test runner uncomment the `CustomConstants` line -on the `Directory.Build.props` - -::: - -Given that the `Core.csproj` is a MAUI project with `net8.0-android;net8.0-ios` target frameworks -and we need `net8.0` for the tests we need a way to add that. The `Core.Test.csproj` has `net8.0` as -a target so by adding the the argument `/p:CustomConstants=UT` we add `UT` as a constant to use in -the projects. With that in place the next things happen: - -- `UT` is added as a constant to use by precompiler directives -- `Core.csproj` is changed to add `net8.0` as a target framework for unit tests -- `FFImageLoading` is removed as a reference given that it doesn't support `net8.0`. Because of - this, now we have a wrapped `CachedImage` that uses the library one if it's not `UT` and a custom - one with NOOP implementation for `UT` - -So if one wants to build the test project, one needs to go to `test/Core.Test` and run: - -```bash -dotnet build -f net8.0 /p:CustomConstants=UT -``` - -and to run the tests go to the same folder and run: - -```bash -dotnet test -f net8.0 /p:CustomConstants=UT -``` - -Finally, when working on the `Core.Test` project or when wanting to use a Test runner, go to the -`Directory.Build.props` (located in the root) and uncomment the line referencing `CustomConstants` -so that everything is loaded accordingly in the project. Because of some issues, the referenced -projects, e.g. `Core`, are only included when the `UT` constant is in place. By uncommenting this -line the projects will be referenced and one can work on that project or run the tests from a Test -runner. - -## Custom constants - -There are custom constants to be used by the parameter `/p:CustomConstants={Value}` when -building/running/releasing: +See the [iOS Mobile app](./ios/index.md) page to set up a Swift development environment. -- `FDROID`: This is used to indicate that it's and F-Droid build/release - ([want to know more?](./android/index.md#f-droid)) -- `UT`: This is used when building/running the test projects or when working on one of them - ([want to know more?](#unit-tests)) +## .NET MAUI Development (legacy) -These constants are added to the defined ones, so anyone can use them in the code with precompiler -directives. +See the [.NET MAUI app](./net-maui-legacy/index.md) page to set up a .NET MAUI development +environment. diff --git a/docs/getting-started/mobile/ios/index.md b/docs/getting-started/mobile/ios/index.md new file mode 100644 index 000000000..3de78a209 --- /dev/null +++ b/docs/getting-started/mobile/ios/index.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# iOS + +How to get started with the iOS Bitwarden project in Swift. + +## Repository + +https://github.com/bitwarden/ios diff --git a/docs/getting-started/mobile/android/android-sdk.png b/docs/getting-started/mobile/net-maui-legacy/android/android-sdk.png similarity index 100% rename from docs/getting-started/mobile/android/android-sdk.png rename to docs/getting-started/mobile/net-maui-legacy/android/android-sdk.png diff --git a/docs/getting-started/mobile/net-maui-legacy/android/index.md b/docs/getting-started/mobile/net-maui-legacy/android/index.md new file mode 100644 index 000000000..d4e9d5c30 --- /dev/null +++ b/docs/getting-started/mobile/net-maui-legacy/android/index.md @@ -0,0 +1,177 @@ +# Android + +:::warning Legacy + +Getting started the **legacy** Android app done in .NET MAUI. + +::: + +## Requirements + +Before you start, you should have the recommended [Tools and Libraries](../../../tools/index.md) +installed. You will also need to install: + +1. Visual Studio 2022 / VS Code +2. [.NET 8 (latest)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) + - Note: Even if you have an ARM64 based Mac (M1, M2, M3, etc.), you can install all x64 SDKs to + run Android + - On Visual Studio for Mac you may need to turn on the feature for .NET 8 by going to Visual + Studio > Preferences > Preview Features > Use the .NET 8 SDK +3. .NET MAUI Workload + - You can install this by running `dotnet workload install maui` +4. Android SDK 34 + - You can use the SDK manager in [Visual Studio][xamarin-vs], or [Android + Studio][android-studio] to install this + +To make sure you have the Android SDK and Emulator installed: + +1. Open Visual Studio +2. Click Tools > SDK Manager (under the Android subheading) +3. Click the Tools tab +4. Make sure the following items are installed: + + - Android SDK tools (at least one version of the command-line tools) + - Android SDK Platform-Tools + - Android SDK Build Tools (at least one version) + - Android Emulator + +5. Click Apply Changes if you've marked anything for installation + +If you've missed anything, Visual Studio should prompt you anyway. + +## Android Development Setup + +To set up a new virtual Android device for debugging: + +1. Click Tools > Device Manager (under the Android subheading) +2. Click New Device +3. Set up the device you want to emulate - you can just choose the Base Device and leave the + default settings if you're unsure +4. Visual Studio will then download the image for that device. The download progress is shown in + the progress in the Android Device Manager dialog. +5. Once this has completed, the emulated Android device will be available as a build target under + App > Debug > (name of device) + +### ARM64 Macs + +1. Install and open Android Studio +2. In the top navbar, click on Android Studio > Settings > Appearance & Behavior (tab) > System + Settings > Android SDK +3. In the SDK Platforms tab, ensure the "Show Package Details" checkbox is checked (located in the + bottom-right) +4. Bellow each Android API you'll see several System Images, pick one of the `ARM 64 v8a` and wait + for it to download +5. Go to View > Tool Windows > Device Manager +6. Inside Device Manager, create a device using the previously downloaded system image + +![Android SDK configuration](android-sdk.png) + +## F-Droid + +On `App.csproj` and `Core.csproj` we can now pass `/p:CustomConstants=FDROID` when +building/releasing so that the `FDROID` constant is added to the defined ones at the project level +and we can use that with precompiler directives, e.g.: + +```c# +#if FDROID + // perform operation only for FDROID. +#endif +``` + +## Building + +There are currently a few problems on Visual Studio for Mac for building correctly the projects, so +if you encounter some errors build using the CLI (previously removing bin/obj folders): + +``` +dotnet build -f net8.0-android -c Debug +``` + +## Testing and Debugging + +### Using the Android Emulator + +In order to access `localhost:` resources in the Android Emulator when debugging using Visual +Studio on your Mac natively, you'll need to configure the endpoint addresses using +``\> in order to access `localhost`, which maps the Android proxy by design. + +[xamarin-vs]: https://learn.microsoft.com/en-us/xamarin/android/get-started/installation/android-sdk +[android-studio]: https://developer.android.com/studio/releases/platforms + +### Using Server Tunneling + +Instead of configuring your device or emulator, you can instead use a +[proxy tunnel to your local server](../../../server/tunnel.md) and have your app connect to it +directly. + +### Push Notifications + +The default configuration for the Android app is to register itself to the same environment as +Bitwarden's QA Cloud. This means that if you try to debug the app using the production endpoints you +won't be able to receive Live Sync updates or Passwordless login requests. + + + +So, in order to receive notifications while debugging, you have two options: + +- Use QA Cloud endpoints for the Api and Identity, or +- Use a local server setup where the Api is connected to QA Azure Notification Hub + + + +### Testing Passwordless Locally + +Before you can start testing and debugging passwordless logins, make sure your local server setup is +running correctly ([server setup](../../../server/guide.md)). You should also be able to deploy your +Android app to your device or emulator. + +:::note + +Debugging and testing passwordless authentication is limited by +[push notifications](#push-notifications). + +::: + +Testing passwordless notifications: + +1. Start your local server (`Api`, `Identity`, `Notifications`) +2. Make sure your mobile device can [connect to your local server](#using-server-tunneling) +3. [Start the web client](../../../clients/web-vault/index.mdx), as you will need it to make login + requests +4. Deploy the Android app to your device or emulator +5. After deployment, open the app, login to your QA account and activate passwordless login requests + in settings +6. Open the web vault using your preferred browser (ex: http://localhost:8080) +7. Enter the email address of an account that has previously authenticated on that device (i.e. is a + "known device") and click Continue. When presented with the login options, click click Login with + Device. +8. Check mobile device for the notification + + + +## AndroidX Credentials + +Currently, the +[androidx.credentials](https://developer.android.com/jetpack/androidx/releases/credentials) official +binding has some bugs and we cannot use it yet. Because of this, we made a binding ourselves which +is located in here: +[Xamarin.AndroidX.Credentials](https://github.com/bitwarden/xamarin.androidx.credentials). + +As of today, we are using version 1.2.0. + +In the projects, the package is added as a local NuGet package located in +`lib/android/Xamarin.AndroidX.Credentials` and this source is already configured in the +`nuget.config` file. + +In the case a change is needed on the binding, create a new local NuGet package and replace it in +the aforementioned source. + +:::warning + +Do not add the project to the solution and as a project reference to the `App.csproj` / +`Core.csproj` this will strangely make the iOS app crash on start because of solution configuration. +Even though we couldn't find the root cause, this is the effect caused by this action. + +::: + + diff --git a/docs/getting-started/mobile/net-maui-legacy/index.md b/docs/getting-started/mobile/net-maui-legacy/index.md new file mode 100644 index 000000000..d8988ba81 --- /dev/null +++ b/docs/getting-started/mobile/net-maui-legacy/index.md @@ -0,0 +1,107 @@ +--- +sidebar_position: 4 +--- + +# .NET MAUI (legacy) + +:::warning Legacy + +Getting started the **legacy** mobile app done in .NET MAUI. + +::: + +## Configure Git blame + +We recommend that you configure git to ignore the Prettier revision: + +```bash +git config blame.ignoreRevsFile .git-blame-ignore-revs +``` + +## Android Development + +See the [Android Mobile app](./android/index.md) page to set up an Android development environment. + +## iOS Development + + + +See the [iOS Mobile app](./ios/index.mdx) page to set up an iOS development environment. + + + + + +Unfortunately, iOS development requires provisioning profiles and other capabilities only available +to internal team members. We do not have any documentation for community developers at this time. + + + +## watchOS Development + + + +See the [watchOS app](./watchos) page to set up an watchOS development environment. + + + + + +Unfortunately, watchOS development requires provisioning profiles and other capabilities only +available to internal team members. We do not have any documentation for community developers at +this time. + + + +## Unit tests + +:::info TL;DR; + +In order to run unit tests add the argument `/p:CustomConstants=UT` on the `dotnet` command for +building/running. To work on Unit testing or use a Test runner uncomment the `CustomConstants` line +on the `Directory.Build.props` + +::: + +Given that the `Core.csproj` is a MAUI project with `net8.0-android;net8.0-ios` target frameworks +and we need `net8.0` for the tests we need a way to add that. The `Core.Test.csproj` has `net8.0` as +a target so by adding the the argument `/p:CustomConstants=UT` we add `UT` as a constant to use in +the projects. With that in place the next things happen: + +- `UT` is added as a constant to use by precompiler directives +- `Core.csproj` is changed to add `net8.0` as a target framework for unit tests +- `FFImageLoading` is removed as a reference given that it doesn't support `net8.0`. Because of + this, now we have a wrapped `CachedImage` that uses the library one if it's not `UT` and a custom + one with NOOP implementation for `UT` + +So if one wants to build the test project, one needs to go to `test/Core.Test` and run: + +```bash +dotnet build -f net8.0 /p:CustomConstants=UT +``` + +and to run the tests go to the same folder and run: + +```bash +dotnet test -f net8.0 /p:CustomConstants=UT +``` + +Finally, when working on the `Core.Test` project or when wanting to use a Test runner, go to the +`Directory.Build.props` (located in the root) and uncomment the line referencing `CustomConstants` +so that everything is loaded accordingly in the project. Because of some issues, the referenced +projects, e.g. `Core`, are only included when the `UT` constant is in place. By uncommenting this +line the projects will be referenced and one can work on that project or run the tests from a Test +runner. + +## Custom constants + +There are custom constants to be used by the parameter `/p:CustomConstants={Value}` when +building/running/releasing: + +- `FDROID`: This is used to indicate that it's and F-Droid build/release + ([want to know more?](./android/index.md#f-droid)) +- `UT`: This is used when building/running the test projects or when working on one of them + ([want to know more?](#unit-tests)) + +These constants are added to the defined ones, so anyone can use them in the code with precompiler +directives. diff --git a/docs/getting-started/mobile/ios/index.mdx b/docs/getting-started/mobile/net-maui-legacy/ios/index.mdx similarity index 98% rename from docs/getting-started/mobile/ios/index.mdx rename to docs/getting-started/mobile/net-maui-legacy/ios/index.mdx index 7f7aa2611..0406b1101 100644 --- a/docs/getting-started/mobile/ios/index.mdx +++ b/docs/getting-started/mobile/net-maui-legacy/ios/index.mdx @@ -8,6 +8,12 @@ import TabItem from "@theme/TabItem"; # iOS +:::warning Legacy + +Getting started the **legacy** iOS app done in .NET MAUI. + +::: + ## Requirements 1. Visual Studio 2022 / VS Code @@ -425,7 +431,7 @@ the bottom popup. ### Using Server Tunneling Instead of configuring your device or emulator to ignore SSL certificates, you can instead use a -[proxy tunnel to your local server](../../server/tunnel.md) and have your app connect to it +[proxy tunnel to your local server](../../../server/tunnel.md) and have your app connect to it directly. ### Push Notifications (Live Sync & Passwordless) diff --git a/docs/getting-started/mobile/ios/new-project-options.png b/docs/getting-started/mobile/net-maui-legacy/ios/new-project-options.png similarity index 100% rename from docs/getting-started/mobile/ios/new-project-options.png rename to docs/getting-started/mobile/net-maui-legacy/ios/new-project-options.png diff --git a/docs/getting-started/mobile/ios/run-debug.png b/docs/getting-started/mobile/net-maui-legacy/ios/run-debug.png similarity index 100% rename from docs/getting-started/mobile/ios/run-debug.png rename to docs/getting-started/mobile/net-maui-legacy/ios/run-debug.png diff --git a/docs/getting-started/mobile/ios/signing-and-capabilities.png b/docs/getting-started/mobile/net-maui-legacy/ios/signing-and-capabilities.png similarity index 100% rename from docs/getting-started/mobile/ios/signing-and-capabilities.png rename to docs/getting-started/mobile/net-maui-legacy/ios/signing-and-capabilities.png diff --git a/docs/getting-started/mobile/ios/troubleshoot-generic-simulator.png b/docs/getting-started/mobile/net-maui-legacy/ios/troubleshoot-generic-simulator.png similarity index 100% rename from docs/getting-started/mobile/ios/troubleshoot-generic-simulator.png rename to docs/getting-started/mobile/net-maui-legacy/ios/troubleshoot-generic-simulator.png diff --git a/docs/getting-started/mobile/watchos/index.mdx b/docs/getting-started/mobile/net-maui-legacy/watchos/index.mdx similarity index 94% rename from docs/getting-started/mobile/watchos/index.mdx rename to docs/getting-started/mobile/net-maui-legacy/watchos/index.mdx index 28381c83e..a14e405b0 100644 --- a/docs/getting-started/mobile/watchos/index.mdx +++ b/docs/getting-started/mobile/net-maui-legacy/watchos/index.mdx @@ -5,6 +5,12 @@ sidebar_custom_props: # watchOS +:::warning Legacy + +Getting started the **legacy** watchOS app done in .NET MAUI. + +::: + ## Requirements Follow the [iOS Setup](../ios/index.mdx). @@ -13,8 +19,8 @@ In order for everything to work properly **devices** are needed. On simulators t won't work (and some other parts may not work as well). Also, have Bluetooth enabled if possible to ease the sync between devices and the debugging communication. -It's recommended to read the [Watch Architecture](../../../../architecture/mobile-clients/watchOS) -as well. +It's recommended to read the +[Watch Architecture](../../../../../architecture/mobile-clients/net-maui-legacy/watchOS) as well. ## macOS Setup