Security and Authentication

Author: simonhamp

resources/views/docs/mobile/2/concepts/authentication.md

@@ -0,0 +1,91 @@
+---
+title: Authentication
+order: 150
+---
+
+## Authenticating Your Users
+
+Most apps will want to have some concept of who the user is so that they can use your app to connect securely with
+external services, such as your API or cloud service.
+
+In a mobile app, you will always need to call an external service (external to the user's device) that acts as the
+source of truth about your users credentials. It could be a service you manage or a third-party service like WorkOS,
+Auth0 or Amazon Cognito.
+
+Authenticating the user serves two purposes:
+
+1. It allows you to prove who they are when they connect to your API.
+2. It gives you an opportunity to grant or deny access to certain features of your app based on the authenticated state
+   of the user.
+
+Whilst some user data may ne stored on the user's device for convenience, you should not rely on this data to
+authenticate the user. This is because **the data is outside of your control**. So you will not be using the typical
+Laravel authentication mechanisms to check for an authenticated user.
+
+<aside>
+
+If you wish to enable or disable parts of your app based on your user's account level or status, make sure you check
+their eligibility based on data from your server on a regular basis, caching it for as short a time as possible on
+their device.
+
+</aside>
+
+## Tokens FTW!
+
+Most mobile apps opt for some form of "auth token" (e.g. a JWT or an expiring API key) that is generated by your auth
+service and stored securely on the user's device.
+
+These tokens should only live for a short period, usually no more than a few days. It's useful to have a single-use
+"refresh token" that lives for a longer time (e.g. 30 days) also shared with your user when they have successfully
+authenticated. This can be exchanged for a new auth token when the user's current auth token has expired.
+
+You should store both auth and refresh tokens in secure storage. **Checking for an auth token's existence to validate
+that the user is authenticated is _not sufficient_.** If the token has expired or been revoked, you should force the
+user to re-authenticate. The only way to know for certain is to exercise the token.
+
+<aside>
+
+#### Pro Tip!
+
+Use `Native\Mobile\Facades\Network::status()` to determine if the device is connected to the internet before making API
+calls.
+
+</aside>
+
+### Laravel Sanctum
+
+[Laravel Sanctum](https://laravel.com/docs/12.x/sanctum) is a very convenient and easy-to-use mechanism for generating
+auth tokens for your users. They simply provide their login credentials and if authenticated, receive a token. Using a
+simple login form, you can collect their username and password in your app and `POST` it securely to your auth service
+via an API call.
+
+Note that, by default, Sanctum tokens don't expire.
+[You should enable token expiration](https://laravel.com/docs/12.x/sanctum#token-expiration) for increased
+security. You may only find out that a token has expired when your app attempts to use it unsuccessfully.
+
+### OAuth
+
+OAuth is a robust and battle-tested solution to the mobile app auth problem. If you're running
+[Laravel Passport](https://laravel.com/docs/12.x/passport) or your authentication service support OAuth, you should use
+it!
+
+You will likely want to use an OAuth client library in your app to make interacting with your OAuth service easier.
+
+When initiating the auth flow for the user, you should use the `Native\Mobile\Facades\Browser::auth()` API, as this is
+purpose-built for securely passing authorization codes back from the OAuth service to your app.
+
+You should set your redirect URL to `nativephp://127.0.0.1/some/route`, where `some/route` is a route you've defined in
+your app's routes that will be able to handle the auth code.
+
+Note that the scheme of the redirect URL in this case is **always** `nativephp://`. This has nothing to do with any
+custom deep link scheme you may have set for your app. It is only tied to the `Browser::auth()` session.
+
+<aside>
+
+Make sure you have good security around your auth service's authentication endpoint. As it will be accessed from many
+devices via an API, standard browser security such as CSRF protections will not be available to you.
+
+Ensure you have appropriate rate limiting in place and even consider using an authentication key that you distribute
+with your apps. These steps will all help defend the endpoint against abuse.
+
+</aside>

resources/views/docs/mobile/2/concepts/security.md

@@ -39,66 +39,60 @@ The device's secure storage encrypts and decrypts data on the fly and that means
 critical things like API tokens, keeping your users and your systems safe.
 
 This data is only accessible by your app and is persisted beyond the lifetime of your app, so it will still be available
-the next time your app is open.
+the next time your app is opened.
 
-### Why not use the Laravel `Crypt` facade?
 
-By default, the `Crypt` facade - and by extension the `encrypt` and `decrypt` helper functions - all rely on the
-`APP_KEY` value set in your `.env` file.
+<aside>
 
-We _will_ use Laravel's underlying `Encryption` class, but you should avoid using these helpers directly.
+Secure Storage is only meant for small amounts of text data, usually no more than a few KBs. If you need to store
+larger amounts of data or files, you should store this in a database or as a file.
 
-In the context of distributed apps, the `APP_KEY` is shipped _with_ your app and therefore isn't secure. Anyone who
-knows where to look for it will be able to find it. Then any data encrypted with it is no better off than if it was
-stored in plain text.
+</aside>
 
-Also, it will be the same key for every user, and this presents a considerable risk.
+### When to use the Laravel `Crypt` facade
 
-What you really want is a **unique key for each user**, and for that you really need to generate your encryption key
-once your app is installed on your user's device.
+When a user first opens your app, NativePHP generates a **unique `APP_KEY` just for their device** and stores it in the
+device's secure storage. This means each instance of your application has its own encryption key that is securely
+stored on the device.
 
-You could do this and update the `.env` file, but it would still be stored in a way that an attacker may be able to
-exploit.
+NativePHP securely reads the `APP_KEY` from secure storage and makes it available to Laravel. So you can safely use the
+`Crypt` facade to encrypt and decrypt data!
 
-A better approach is to generate a secure key the first time your app opens, place that key in Secure Storage, and
-then use that key to encrypt your other data before storage:
+<aside>
 
-```php
-use Illuminate\Encryption\Encrypter;
-use Illuminate\Support\Facades\Storage;
-use Native\Mobile\Facades\SecureStorage;
+Make sure you do not leak the `APP_KEY` or decrypted data inadvertently through error tracking or debug logging tools.
 
-function generateRandomKey()
-{
-    return base64_encode(
-        Encrypter::generateKey(config('app.cipher'))
-    );
-}
+</aside>
 
-$encryptionKey = SecureStorage::get('encryption_key');
+This is great for encrypting larger amounts of data that wouldn't easily fit in secure storage. You can encrypt values
+and store them in the file system or in the SQLite database, knowing that they are safe at rest:
 
-if (! $encryptionKey) {
-    SecureStorage::set('encryption_key', $encryptionKey = generateRandomKey());
-}
-
-$mobileEncrypter = new Encrypter($encryptionKey);
+```php
+use Illuminate\Support\Facades\Crypt;
 
-$encryptedContents = $mobileEncrypter->encrypt(
+$encryptedContents = Crypt::encryptString(
     $request->file('super_private_file')
 );
 
-Storage::put('my_secure_file.pdf', $encryptedContents);
+Storage::put('my_secure_file', $encryptedContents);
 ```
 
 And then decrypt it later:
 
 ```php
-$decryptedContents = $mobileEncrypter->decrypt(
-    Storage::get('my_secure_file.pdf')
+$decryptedContents = Crypt::decryptString(
+    Storage::get('my_secure_file')
 );
 ```
 
-### Secure Storage vs Database/Files
+<aside>
+
+Data encrypted with the `Crypt` facade should stay on the user's device with your app. Placing it encrypted anywhere
+else risks the chance that it will be unrecoverable. If the user loses their device or deletes your app,
+they will lose the encryption key and the data will be encrypted forever.
+
+If you wish to share data, decrypt it first, transmit securely (e.g. over HTTPS) and re-encrypt it with a different key
+that is safely managed elsewhere.
+
+</aside>
 
-Secure Storage is only meant for small amounts of text data, usually no more than a few KBs. If you need to store
-larger amounts of data or files, you should store this in a database or as a file.