feat(oauth2): support custom URI schemes for Native clients across redirect_uris, allowed_origins, post_logout_redirect_uris

Native (mobile/desktop) OAuth2 clients can now register custom app
schemes (myapp://callback) in allowed_origins and
post_logout_redirect_uris via the admin API and React UI, matching
the support redirect_uris already had. The OIDC end-session flow
honors a registered custom-scheme post-logout URI at runtime.

Security hardening (found via adversarial code review):
- Deny-list for dangerous/launch pseudo-schemes (javascript:, data:,
  intent:, etc.) and plain http, centralized in HttpUtils and shared
  by write-time validation (ClientService) and runtime allow-gates
  (Client::isUriAllowed/isPostLogoutUriAllowed).
- RFC 8252 loopback carve-out: http://127.0.0.1|localhost redirect
  URIs remain allowed for Native clients (the standard native-app
  pattern), only non-loopback http is blocked.
- Cross-client custom-scheme uniqueness check extended to all three
  URI fields (was redirect_uris only), preventing OS-level scheme
  interception between clients.
- Defense-in-depth: runtime gates independently re-check the scheme
  deny-list rather than relying solely on write-time validation.
- Fixed a pre-existing crash (missing array key "host") in
  URLUtils::canonicalUrl/Client::isPostLogoutUriAllowed for host-less
  custom-scheme URIs (mailto:, file:///x).
- Fixed a pre-existing substring false-positive in the cross-client
  scheme collision check (e.g. "roipapp" matching inside
  "androipapp://...").

Also fixes an unrelated pre-existing bug in UserLoginTurnstileTest
where assigning null (from an unset env var) to a typed string
property threw a TypeError before the intended skip-guard could run.

Plan: docs/plans/2026-07-14-native-clients-custom-schemes.md

Author: smarcet

app/Http/Controllers/Api/ClientApiController.php

@@ -699,8 +699,8 @@ protected function getUpdatePayloadValidationRules(): array
             'tos_uri'                         => 'nullable|url',
             'redirect_uris'                   => 'nullable|custom_url_set:application_type',
             'policy_uri'                      => 'nullable|url',
-            'post_logout_redirect_uris'       => 'nullable|ssl_url_set',
-            'allowed_origins'                 => 'nullable|ssl_url_set',
+            'post_logout_redirect_uris'       => 'nullable|custom_url_set:application_type',
+            'allowed_origins'                 => 'nullable|custom_url_set:application_type',
             'logout_uri'                      => 'nullable|url',
             'logout_session_required'         => 'sometimes|required|boolean',
             'logout_use_iframe'               => 'sometimes|required|boolean',

app/Models/OAuth2/Client.php

@@ -14,6 +14,7 @@
 
 use App\libs\Utils\URLUtils;
 use Auth\User;
+use Utils\Http\HttpUtils;
 use Doctrine\Common\Collections\Criteria;
 use Illuminate\Support\Facades\Config;
 use Illuminate\Support\Facades\Log;
@@ -629,13 +630,34 @@ public function isScopeAllowed(string $scope):bool
         return $res;
     }
 
+    /**
+     * Single source of truth for "is this scheme dangerous for a Native client" across the runtime allow-gates
+     * (isUriAllowed for redirect_uris, isPostLogoutUriAllowed for post_logout_redirect_uris). Delegates the
+     * actual deny-list to HttpUtils, which ClientService's write-time validation also uses.
+     *
+     * @param string $scheme
+     * @param string|null $host enables the RFC 8252 http-loopback carve-out (see HttpUtils::isDisallowedNativeUriScheme)
+     * @return bool
+     */
+    private function isNativeDangerousScheme(string $scheme, ?string $host = null): bool
+    {
+        return $this->application_type === IClient::ApplicationType_Native && HttpUtils::isDisallowedNativeUriScheme($scheme, $host);
+    }
+
     /**
      * @param string $uri
      * @return bool
      */
     public function isUriAllowed(string $uri):bool
     {
         Log::debug(sprintf("Client::isUriAllowed client %s original uri %s", $this->client_id, $uri));
+
+        $original_parts = @parse_url($uri);
+        if ($original_parts !== false && isset($original_parts['scheme']) && $this->isNativeDangerousScheme($original_parts['scheme'], $original_parts['host'] ?? null)) {
+            Log::debug(sprintf("Client::isUriAllowed url %s scheme is not allowed for native client %s", $uri, $this->client_id));
+            return false;
+        }
+
         $uri = URLUtils::canonicalUrl($uri);
         if(empty($uri)) {
             Log::debug(sprintf("Client::isUriAllowed url %s is not valid", $uri));
@@ -1097,17 +1119,33 @@ public function isPostLogoutUriAllowed($post_logout_uri)
         if ($parts == false) {
             return false;
         }
-        if($parts['scheme']!=='https')
+        // native clients may register custom schemes (myapp://...); every other app type requires https
+        if($this->application_type !== IClient::ApplicationType_Native && strtolower($parts['scheme'])!=='https')
             return false;
 
-        $logout_without_port = $parts['scheme'].'://'.$parts['host'];
+        // defense-in-depth: re-check the scheme deny-list at the runtime allow-gate, not just at write time
+        // (ClientService::assertNativeCustomSchemesAllowed). A row can reach storage through a path other than
+        // ClientService (e.g. ClientFactory::build() called directly by a seeder or a future write path), so
+        // the gate that actually authorizes the live 302 redirect must not be the only enforcement point.
+        if($this->isNativeDangerousScheme($parts['scheme'], $parts['host'] ?? null))
+            return false;
+
+        // host-less URIs (e.g. mailto:, file:///x, myapp:///cb) pass FILTER_VALIDATE_URL but have no
+        // authority to match against; without this guard the concatenation below raises an
+        // "Undefined array key host" warning (converted to ErrorException) on the public end-session endpoint.
+        if(!isset($parts['host'])) return false;
+
+        // scheme/host are case-insensitive (RFC 3986); the write path normally lowercases the stored value,
+        // but match case-insensitively regardless so a bypassing write path can't silently break matching.
+        $stored_post_logout_uris = strtolower($this->post_logout_redirect_uris);
+        $logout_without_port = strtolower($parts['scheme'].'://'.$parts['host']);
 
-        if(str_contains($this->post_logout_redirect_uris, $logout_without_port )) return true;
+        if(str_contains($stored_post_logout_uris, $logout_without_port )) return true;
 
         if(isset($parts['port']))
         {
-            $logout_with_port    = $parts['scheme'].'://'.$parts['host'].':'.$parts['port'];
-            return str_contains($this->post_logout_redirect_uris, $logout_with_port );
+            $logout_with_port    = $logout_without_port.':'.$parts['port'];
+            return str_contains($stored_post_logout_uris, $logout_with_port );
         }
         return false;
     }

app/Repositories/DoctrineOAuth2ClientRepository.php

@@ -163,19 +163,44 @@ public function getByOrigin(string $origin):?Client
     }
 
     /**
+     * Interception-prevention rule checked across all three URI-bearing fields (redirect_uris,
+     * post_logout_redirect_uris, allowed_origins): whichever field a scheme was first claimed in, another
+     * client re-registering it in ANY of the three fields creates the same OS-level scheme-collision risk
+     * (the OS routes a custom-scheme redirect to whichever installed app claims it, regardless of which
+     * field of which client this server thinks it belongs to).
+     *
      * @param int $id
      * @param string $custom_scheme
      * @return bool
      */
-    public function hasCustomSchemeRegisteredForRedirectUrisOnAnotherClientThan(int $id, string $custom_scheme): bool
+    public function hasCustomSchemeRegisteredOnAnotherClientThan(int $id, string $custom_scheme): bool
     {
-        return $this->getEntityManager()
-            ->createQueryBuilder()
+        $scheme = trim($custom_scheme);
+        // fields are comma-separated URI lists; a plain '%scheme://%' substring match false-positives on any
+        // longer scheme ending in this one (e.g. 'roipapp' matching inside 'androipapp://...'). Anchor the
+        // match to a real list-item boundary: the scheme starts the field, or immediately follows a comma.
+        $starts_with = $scheme . '://%';
+        $after_comma = '%,' . $scheme . '://%';
+
+        $qb = $this->getEntityManager()->createQueryBuilder();
+        $matches_field = function (string $field) use ($qb) {
+            return $qb->expr()->orX(
+                $qb->expr()->like($field, ':starts_with'),
+                $qb->expr()->like($field, ':after_comma')
+            );
+        };
+
+        return $qb
             ->select("count(e.id)")
             ->from($this->getBaseEntity(), "e")
-            ->where("e.redirect_uris like :custom_scheme")
+            ->where($qb->expr()->orX(
+                $matches_field("e.redirect_uris"),
+                $matches_field("e.post_logout_redirect_uris"),
+                $matches_field("e.allowed_origins")
+            ))
             ->andWhere("e.id <> :id")
-            ->setParameter("custom_scheme", '%' . trim($custom_scheme). '://%')
+            ->setParameter("starts_with", $starts_with)
+            ->setParameter("after_comma", $after_comma)
             ->setParameter("id", $id)
             ->setMaxResults(1)
             ->getQuery()

app/Services/OAuth2/ClientService.php

@@ -220,6 +220,40 @@ public function getCurrentClientAuthInfo()
         throw new InvalidClientAuthMethodException;
     }
 
+    /**
+     * Native clients may register genuine custom app URI schemes (e.g. myapp://, com.example.app://) in
+     * allowed_origins and post_logout_redirect_uris. They may NOT register plain http:// outside the RFC 8252
+     * loopback carve-out, nor dangerous/launch pseudo-schemes (javascript:, data:, intent:, ...): at
+     * end-session these fields become live 302 redirect targets. See HttpUtils::DISALLOWED_NATIVE_URI_SCHEMES
+     * for the deny-list (shared with the runtime allow-gates in Client::isUriAllowed/isPostLogoutUriAllowed).
+     * Also enforces the same cross-client scheme-uniqueness rule redirect_uris already has, since a scheme
+     * claimed by another client here creates the identical OS-level interception risk.
+     *
+     * @param array $payload
+     * @param int $exclude_client_id the client being written; -1 (never a real id) when creating a new one
+     * @throws ValidationException
+     */
+    private function assertNativeCustomSchemesAllowed(array $payload, int $exclude_client_id = -1): void
+    {
+        foreach (['allowed_origins', 'post_logout_redirect_uris'] as $field) {
+            if (empty($payload[$field])) continue;
+            foreach (explode(',', $payload[$field]) as $uri) {
+                $parts = @parse_url(trim($uri));
+                if (!isset($parts['scheme'])) {
+                    throw new ValidationException(sprintf('invalid scheme on %s uri.', $field));
+                }
+                $scheme = strtolower($parts['scheme']);
+                if (HttpUtils::isDisallowedNativeUriScheme($scheme, $parts['host'] ?? null)) {
+                    throw new ValidationException(sprintf('scheme %s:// is not allowed.', $scheme));
+                }
+                if (HttpUtils::isCustomSchema($scheme)
+                    && $this->client_repository->hasCustomSchemeRegisteredOnAnotherClientThan($exclude_client_id, $scheme)) {
+                    throw new ValidationException(sprintf('schema %s:// already registered for another client.', $scheme));
+                }
+            }
+        }
+    }
+
     /**
      * @param array $payload
      * @return IEntity
@@ -238,6 +272,12 @@ public function create(array $payload):IEntity
                 throw new ValidationException('there is already another application with that name, please choose another one.');
             }
 
+            // close the create-path bypass: the same scheme allow-list update() enforces (only reachable
+            // for native clients, where the runtime https gate is relaxed).
+            if (($payload['application_type'] ?? null) === IClient::ApplicationType_Native) {
+                $this->assertNativeCustomSchemesAllowed($payload);
+            }
+
             $client = ClientFactory::build($payload);
             $client = $this->client_credential_generator->generate($client);
 
@@ -307,20 +347,22 @@ public function update(int $id, array $payload):IEntity
                                 if (!isset($uri['scheme'])) {
                                     throw new ValidationException('invalid scheme on redirect uri.');
                                 }
-                                if (HttpUtils::isCustomSchema($uri['scheme'])) {
-                                    if ($this->client_repository->hasCustomSchemeRegisteredForRedirectUrisOnAnotherClientThan($id, $uri['scheme'])) {
-                                        throw new ValidationException(sprintf('schema %s:// already registered for another client.',
-                                            $uri['scheme']));
-                                    }
-                                } else {
-                                    if (!HttpUtils::isHttpSchema($uri['scheme'])) {
-                                        throw new ValidationException(sprintf('scheme %s:// is invalid.',
-                                            $uri['scheme']));
-                                    }
+                                if (HttpUtils::isDisallowedNativeUriScheme($uri['scheme'], $uri['host'] ?? null)) {
+                                    throw new ValidationException(sprintf('scheme %s:// is not allowed.', $uri['scheme']));
+                                }
+                                // the else branch previously here (rejecting non-http(s) "non-custom" schemes)
+                                // is unreachable now: ftp/file and non-loopback http are already rejected by
+                                // the deny-list check above, and https/loopback-http both satisfy isHttpSchema.
+                                if (HttpUtils::isCustomSchema($uri['scheme'])
+                                    && $this->client_repository->hasCustomSchemeRegisteredOnAnotherClientThan($id, $uri['scheme'])) {
+                                    throw new ValidationException(sprintf('schema %s:// already registered for another client.',
+                                        $uri['scheme']));
                                 }
                             }
                         }
                     }
+
+                    $this->assertNativeCustomSchemesAllowed($payload, $id);
                 }
                 break;
                 case IClient::ApplicationType_Web_App:

app/libs/OAuth2/Repositories/IClientRepository.php

@@ -55,5 +55,5 @@ public function getByOrigin(string $origin):?Client;
      * @param string $custom_scheme
      * @return bool
      */
-    public function hasCustomSchemeRegisteredForRedirectUrisOnAnotherClientThan(int $id, string $custom_scheme):bool;
+    public function hasCustomSchemeRegisteredOnAnotherClientThan(int $id, string $custom_scheme):bool;
 }

app/libs/Utils/Http/HttpUtils.php

@@ -18,6 +18,44 @@
  */
 final class HttpUtils
 {
+    /**
+     * Schemes native clients may NOT register in redirect_uris / allowed_origins / post_logout_redirect_uris,
+     * even though they are otherwise allowed to register arbitrary custom app schemes there. https is always
+     * allowed (checked separately); plain http is handled separately too (see isDisallowedNativeUriScheme -
+     * RFC 8252 loopback redirection is a carve-out). Every scheme below, once handed to an OS/browser as a
+     * live redirect target, can trigger an unintended action (script execution, app launch, install prompt,
+     * local file/content access). Single source of truth for the write-time validator
+     * (ClientService::assertNativeCustomSchemesAllowed) and the runtime allow-gates (Client::isUriAllowed,
+     * Client::isPostLogoutUriAllowed).
+     */
+    public const array DISALLOWED_NATIVE_URI_SCHEMES = [
+        'javascript', 'data', 'vbscript', 'intent', 'file', 'ftp', 'blob', 'about', 'mailto', 'tel',
+        'itms-services', 'market', 'sms', 'content', 'chrome-extension', 'filesystem', 'view-source',
+        'ws', 'wss', 'googlechrome', 'applewebdata',
+    ];
+
+    /**
+     * Loopback hosts exempted from the "plain http is disallowed" rule (RFC 8252 SS7.3): a native app
+     * receiving its own redirect on 127.0.0.1/::1/localhost never sends the request over the network, so
+     * there is no TLS downgrade to protect against.
+     */
+    public const array NATIVE_LOOPBACK_HOSTS = ['127.0.0.1', '::1', '[::1]', 'localhost'];
+
+    /**
+     * @param string $schema
+     * @param string|null $host present when validating a full URI (e.g. redirect_uris); enables the
+     *                          RFC 8252 http-loopback carve-out. Omit when only the scheme is known.
+     * @return bool
+     */
+    public static function isDisallowedNativeUriScheme(string $schema, ?string $host = null): bool
+    {
+        $schema = strtolower($schema);
+        if ($schema === 'http') {
+            return !in_array(strtolower((string)$host), self::NATIVE_LOOPBACK_HOSTS);
+        }
+        return in_array($schema, self::DISALLOWED_NATIVE_URI_SCHEMES);
+    }
+
     /**
      * @param string $schema
      * @return bool

app/libs/Utils/URLUtils.php

@@ -40,6 +40,11 @@ public static function canonicalUrl(string $url, bool $usePort = true):?string{
         {
             return null;
         }
+        // host-less URIs (e.g. mailto:, file:///x) pass FILTER_VALIDATE_URL but have no authority to
+        // canonicalize; without this guard the concatenation below raises an "Undefined array key host" warning.
+        if (!isset($parts['host'])) {
+            return null;
+        }
         $canonical_url = $parts['scheme'].'://'.strtolower($parts['host']);
         if(isset($parts['port']) && $usePort) {
             $canonical_url .= ':'.strtolower($parts['port']);

resources/js/oauth2/profile/edit_client/components/logout_options.js

@@ -10,10 +10,27 @@ import TagsInput, {getTags} from "../../../../components/tags_input";
 
 import styles from "./common.module.scss";
 
-const LogoutOptions = ({initialValues, onSavePromise}) => {
+// mirrors HttpUtils::$disallowed_native_uri_schemes on the backend; keep the two lists in sync.
+const DISALLOWED_NATIVE_SCHEMES = [
+    'http:', 'javascript:', 'data:', 'vbscript:', 'intent:', 'file:', 'ftp:', 'blob:', 'about:', 'mailto:', 'tel:',
+    'itms-services:', 'market:', 'sms:', 'content:', 'chrome-extension:', 'filesystem:', 'view-source:',
+    'ws:', 'wss:', 'googlechrome:', 'applewebdata:',
+];
+
+const LogoutOptions = ({appTypes, initialValues, onSavePromise}) => {
     const [loading, setLoading] = useState(false);
 
     const validatePostLogoutRedirectURI = (value) => {
+        // native clients may register genuine custom app schemes (myapp://...) or https, but not plain http
+        // nor dangerous/launch pseudo-schemes (javascript:, data:, intent:, ...): matches the backend allow-list.
+        if (initialValues.application_type === appTypes.Native) {
+            try {
+                const protocol = new URL(value).protocol.toLowerCase();
+                return protocol === 'https:' || !DISALLOWED_NATIVE_SCHEMES.includes(protocol);
+            } catch (err) {
+                return false;
+            }
+        }
         const regex = /^https:\/\/([\w@][\w.:@]+)\/?[\w\.?=%&=\-@/$,]*$/ig;
         return regex.test(value);
     }
@@ -72,7 +89,6 @@ const LogoutOptions = ({initialValues, onSavePromise}) => {
                             fullWidth
                             size="small"
                             variant="outlined"
-                            type="url"
                             tags={getTags(formik.values.post_logout_redirect_uris)}
                             errors={formik.errors.post_logout_redirect_uris}
                             onChange={formik.handleChange}

resources/js/oauth2/profile/edit_client/components/security_settings_panel.js

@@ -295,7 +295,7 @@ const SecuritySettingsPanel = (
                 </>
             </Grid>
             <Grid item container>
-                <LogoutOptions initialValues={initialValues} onSavePromise={onLogoutOptionsSavePromise}/>
+                <LogoutOptions appTypes={appTypes} initialValues={initialValues} onSavePromise={onLogoutOptionsSavePromise}/>
             </Grid>
         </Grid>
     );