@sesamy/sesamy-js 1.40.1 → 1.40.3

package/README.md

@@ -171,8 +171,10 @@ These are the available configuration options, with their default values:
     clientId: null,
     organization: null,
     enabled: true,
-    endpoint: 'https://auth.sesamy.com',
-    redirectUri: window.location.origin
+    domain: null,        // Optional: custom Auth0 domain (e.g., 'auth.example.com')
+    domains: [],         // Optional: array of domain configurations for multi-domain setups
+    usePopupForSafari: false,   // Optional: use popup login instead of redirect on Safari
+    usePopupForAndroid: false   // Optional: use popup login instead of redirect on Android
   },
   content: [
     {
@@ -204,6 +206,157 @@ These are the available configuration options, with their default values:
 }
 ```
 
+# Authentication Configuration
+
+The `auth` configuration object controls how the Sesamy library handles user authentication. Below are the available options:
+
+## Basic Configuration
+
+```javascript
+{
+  auth: {
+    clientId: 'your-client-id',  // Required: Your Auth0 client ID
+    organization: 'org_123',      // Optional: Auth0 organization ID
+    enabled: true                  // Optional: Enable/disable authentication (default: true)
+  }
+}
+```
+
+## Custom Domain Configuration
+
+### Single Domain
+
+For custom Auth0 domains, use the `domain` property:
+
+```javascript
+{
+  auth: {
+    clientId: 'your-client-id',
+    domain: 'auth.example.com'    // Optional: Custom Auth0 domain
+  }
+}
+```
+
+### Multiple Domains (Multi-tenant/White-label)
+
+For applications that operate across multiple domains (e.g., white-label solutions, multi-region setups), use the `domains` array. The library will automatically select the appropriate auth domain based on the current page's top-level domain:
+
+```javascript
+{
+  auth: {
+    clientId: 'your-client-id',
+    domains: [
+      {
+        domain: 'auth.brand1.com',
+        topLevelDomain: 'brand1.com'  // Optional: explicit TLD to match
+      },
+      {
+        domain: 'auth.brand2.com',
+        topLevelDomain: 'brand2.com'
+      },
+      {
+        domain: 'auth.example.co.uk'  // topLevelDomain is auto-derived as 'example.co.uk'
+      }
+    ],
+    domain: 'default-auth.example.com'  // Optional: fallback if no match found
+  }
+}
+```
+
+**How it works:**
+
+1. The library extracts the top-level domain from the current page URL
+2. It searches the `domains` array for a matching configuration
+3. If a match is found, that domain is used for authentication
+4. If no match is found, it falls back to the `domain` property
+5. If neither is available, it uses the default Sesamy auth domain
+
+**Example scenarios:**
+
+```javascript
+// Multi-region setup
+{
+  auth: {
+    clientId: 'your-client-id',
+    domains: [
+      { domain: 'auth.us.example.com', topLevelDomain: 'example.com' },
+      { domain: 'auth.uk.example.co.uk', topLevelDomain: 'example.co.uk' },
+      { domain: 'auth.au.example.com.au', topLevelDomain: 'example.com.au' }
+    ]
+  }
+}
+
+// White-label setup
+{
+  auth: {
+    clientId: 'your-client-id',
+    domains: [
+      { domain: 'auth.client1.com' },
+      { domain: 'auth.client2.com' },
+      { domain: 'auth.client3.com' }
+    ],
+    domain: 'auth.myplatform.com'  // Default for unlisted domains
+  }
+}
+```
+
+## Login Method Configuration
+
+### Safari and iOS Popup Login
+
+By default, the library uses redirect-based login. However, Safari and iOS browsers may require popup-based login in certain scenarios (e.g., incognito mode, cross-domain authentication):
+
+```javascript
+{
+  auth: {
+    clientId: 'your-client-id',
+    usePopupForSafari: true   // Optional: force popup login on Safari (default: false)
+  }
+}
+```
+
+### Android Popup Login
+
+For Android in-app browsers or WebViews, you may want to use popup-based login:
+
+```javascript
+{
+  auth: {
+    clientId: 'your-client-id',
+    usePopupForAndroid: true  // Optional: force popup login on Android (default: false)
+  }
+}
+```
+
+## Complete Example
+
+```javascript
+{
+  clientId: "demo",
+  organization: "org_abc123",
+  auth: {
+    clientId: "demo",
+    organization: "org_abc123",
+    enabled: true,
+    domains: [
+      { domain: 'auth.example.com', topLevelDomain: 'example.com' },
+      { domain: 'auth.example.co.uk', topLevelDomain: 'example.co.uk' }
+    ],
+    domain: 'auth.fallback.com',
+    usePopupForSafari: true,
+    usePopupForAndroid: false
+  }
+}
+```
+
+## Cross-Domain Authentication
+
+When your application domain differs from your Auth0 domain's top-level domain, the library automatically uses popup-based login to handle cross-domain authentication properly. For example:
+
+- Your app: `app.example.com`
+- Auth domain: `auth.different.com`
+- Result: Popup login is automatically used
+
 # Custom HTML Attributes
 
 ## Visibility