| 1 | # Migration guide — from proxy/native-form auth to hosted auth |
| 2 | |
| 3 | This guide is for teams currently using: |
| 4 | |
| 5 | - a backend or BFF proxy for login/signup |
| 6 | - native email/password forms in the app |
| 7 | - confidential smbCloud Auth credentials stored on the server |
| 8 | |
| 9 | and who want to move Apple apps toward the hosted public-client SDK model. |
| 10 | |
| 11 | ## When to migrate |
| 12 | |
| 13 | Move to hosted auth when: |
| 14 | |
| 15 | - your Apple app is a public client |
| 16 | - you want to stop maintaining auth proxy glue in the app layer |
| 17 | - you want browser/session based login with PKCE |
| 18 | - you do not need a custom native email/password screen as the primary flow |
| 19 | |
| 20 | Keep the proxy/BFF model when: |
| 21 | |
| 22 | - your product requires native credential forms |
| 23 | - your backend owns broader session orchestration |
| 24 | - you need server-managed trust boundaries beyond public-client hosted auth |
| 25 | |
| 26 | ## Old model |
| 27 | |
| 28 | 1. user enters email and password into the app |
| 29 | 2. app sends credentials to your backend |
| 30 | 3. backend uses confidential smbCloud Auth credentials |
| 31 | 4. backend returns an app-safe response |
| 32 | |
| 33 | ## Hosted auth model |
| 34 | |
| 35 | 1. app calls `SmbCloudWebAuth.login(...)` |
| 36 | 2. SDK opens hosted auth in `ASWebAuthenticationSession` |
| 37 | 3. user completes login in the system browser session |
| 38 | 4. SDK validates callback `state` and exchanges the code with PKCE |
| 39 | 5. app persists the returned `SmbCloudSession` |
| 40 | 6. app loads profile data with `userInfo(...)` |
| 41 | |
| 42 | ## Migration plan |
| 43 | |
| 44 | ### 1. Keep server-side auth for native forms if still needed |
| 45 | |
| 46 | Do not remove your proxy if the product still depends on native credential entry. |
| 47 | Hosted auth and proxy-based auth can coexist during migration. |
| 48 | |
| 49 | ### 2. Add a public client in smbCloud Auth |
| 50 | |
| 51 | The Apple app should use a public client identifier and a callback URL such as: |
| 52 | |
| 53 | - `myapp://auth/callback` |
| 54 | |
| 55 | Do not copy confidential secrets into the app. |
| 56 | |
| 57 | ### 3. Replace app-side login orchestration |
| 58 | |
| 59 | Replace custom login glue with: |
| 60 | |
| 61 | - `SmbCloudWebAuth` |
| 62 | - `SmbCloudCredentialsManager` |
| 63 | - `SmbCloudUserInfoClient` if you want standalone profile fetches |
| 64 | |
| 65 | ### 4. Move local session storage to Keychain |
| 66 | |
| 67 | Persist `SmbCloudSession` with `SmbCloudCredentialsManager` instead of keeping access tokens in plaintext storage. |
| 68 | |
| 69 | ### 5. Update your UX copy |
| 70 | |
| 71 | Hosted auth changes the user experience from a native email/password form to a system browser-backed sign-in flow. |
| 72 | Prepare copy, onboarding, and support docs accordingly. |
| 73 | |
| 74 | ## What changes in app code |
| 75 | |
| 76 | ### Before |
| 77 | |
| 78 | - app owns email/password UI |
| 79 | - app talks to your backend for auth |
| 80 | - backend owns smbCloud Auth credentials |
| 81 | |
| 82 | ### After |
| 83 | |
| 84 | - app launches hosted auth via `SmbCloudWebAuth.login(...)` |
| 85 | - SDK handles PKCE and callback validation |
| 86 | - app stores `SmbCloudSession` |
| 87 | - app fetches user info with the access token |
| 88 | |
| 89 | ## Security benefits |
| 90 | |
| 91 | - no confidential smbCloud Auth secret inside the shipped app |
| 92 | - no embedded webview login flow |
| 93 | - PKCE protects the public-client authorization code flow |
| 94 | - system browser sessions align with Apple platform expectations |
| 95 | |
| 96 | ## What does not change |
| 97 | |
| 98 | If you still need native forms, a BFF/proxy remains the correct architecture. |
| 99 | This SDK does not try to replace secure server-side confidential flows for those cases. |
| 100 | |
| 101 | ## Recommended rollout |
| 102 | |
| 103 | 1. introduce hosted auth for new sign-ins |
| 104 | 2. keep proxy-based flows for legacy/native-form users if necessary |
| 105 | 3. migrate session restoration to `SmbCloudCredentialsManager` |
| 106 | 4. retire app-specific auth glue once the hosted path is the default |
| 107 | |
| 108 | ## Related docs |
| 109 | |
| 110 | - `Docs/QuickStart-iOS.md` |
| 111 | - `Docs/QuickStart-macOS.md` |