feat: validate bcp47 language tags with a regex

azmeuk · azmeuk · commit 1c9ae3a34345 · 2026-03-23T12:06:50.000+01:00
diff --git a/authlib/common/language.py b/authlib/common/language.py
@@ -0,0 +1,13 @@
+import re
+
+# Structurally validates BCP 47 language tags (RFC 5646).
+# Accepts private-use tags (x-...) and standard tags (2-8 alpha + optional subtags).
+# Does not validate subtags against the IANA registry.
+_LANGUAGE_TAG_RE = re.compile(
+    r"^(x(-[a-zA-Z0-9]{1,8})+|[a-zA-Z]{2,8}(-[a-zA-Z0-9]{1,8})*)$"
+)
+
+
+def is_valid_language_tag(tag):
+    """Return True if tag is a structurally valid BCP 47 language tag."""
+    return isinstance(tag, str) and bool(_LANGUAGE_TAG_RE.match(tag))
diff --git a/authlib/oauth2/rfc8414/models.py b/authlib/oauth2/rfc8414/models.py
@@ -1,3 +1,4 @@
+from authlib.common.language import is_valid_language_tag
 from authlib.common.security import is_secure_transport
 from authlib.common.urls import is_valid_url
 from authlib.common.urls import urlparse
@@ -208,7 +209,7 @@ def validate_ui_locales_supported(self):
         [RFC5646].  If omitted, the set of supported languages and scripts
         is unspecified.
         """
-        validate_array_value(self, "ui_locales_supported")
+        validate_language_tags_array(self, "ui_locales_supported")
 
     def validate_op_policy_uri(self):
         """OPTIONAL.  URL that the authorization server provides to the
@@ -411,6 +412,15 @@ def validate_array_value(metadata, key):
         raise ValueError(f'"{key}" MUST be JSON array')
 
 
+def validate_language_tags_array(metadata, key):
+    validate_array_value(metadata, key)
+    values = metadata.get(key)
+    if values is not None:
+        for tag in values:
+            if not is_valid_language_tag(tag):
+                raise ValueError(f'"{key}" MUST contain BCP 47 language tags')
+
+
 def validate_boolean_value(metadata, key):
     if key not in metadata:
         return
diff --git a/authlib/oidc/core/claims.py b/authlib/oidc/core/claims.py
@@ -6,6 +6,7 @@
 from joserfc.errors import MissingClaimError
 
 from authlib.common.encoding import to_bytes
+from authlib.common.language import is_valid_language_tag
 from authlib.oauth2.claims import JWTClaims
 from authlib.oauth2.rfc6749.util import scope_to_list
 
@@ -244,6 +245,12 @@ class UserInfo(dict):
         "phone": ["phone_number", "phone_number_verified"],
     }
 
+    def validate_locale(self):
+        """Validate the locale claim is a BCP 47 language tag."""
+        locale = self.get("locale")
+        if locale is not None and not is_valid_language_tag(locale):
+            raise ValueError('"locale" MUST be a BCP 47 language tag')
+
     def filter(self, scope: str):
         """Return a new UserInfo object containing only the claims matching the scope passed in parameter."""
         scope = scope_to_list(scope)
diff --git a/authlib/oidc/discovery/models.py b/authlib/oidc/discovery/models.py
@@ -1,6 +1,7 @@
 from authlib.oauth2.rfc8414 import AuthorizationServerMetadata
 from authlib.oauth2.rfc8414.models import validate_array_value
 from authlib.oauth2.rfc8414.models import validate_boolean_value
+from authlib.oauth2.rfc8414.models import validate_language_tags_array
 
 
 class OpenIDProviderMetadata(AuthorizationServerMetadata):
@@ -236,7 +237,7 @@ def validate_claims_locales_supported(self):
         language tag values. Not all languages and scripts are necessarily
         supported for all Claim values.
         """
-        validate_array_value(self, "claims_locales_supported")
+        validate_language_tags_array(self, "claims_locales_supported")
 
     def validate_claims_parameter_supported(self):
         """OPTIONAL. Boolean value specifying whether the OP supports use of
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -26,6 +26,8 @@ Version 1.7.0
 - RFC7523 accepts the issuer URL as a valid audience. :issue:`730`
 - Fix ``InvalidTokenError`` extra attributes being wrapped instead of passed as
   individual key=value pairs in the ``WWW-Authenticate`` header. :pr:`872`
+- Validate BCP 47 language tags in ``ui_locales_supported``, ``claims_locales_supported``
+  and ``UserInfo.locale``. :pr:`873`
 
 Upgrade Guide: :ref:`joserfc_upgrade`.
 
diff --git a/tests/core/test_oauth2/test_rfc8414.py b/tests/core/test_oauth2/test_rfc8414.py
@@ -260,14 +260,38 @@ def test_validate_ui_locales_supported():
     metadata = AuthorizationServerMetadata()
     metadata.validate_ui_locales_supported()
 
+    # valid
+    metadata = AuthorizationServerMetadata({"ui_locales_supported": ["en"]})
+    metadata.validate_ui_locales_supported()
+
+    metadata = AuthorizationServerMetadata(
+        {"ui_locales_supported": ["en-US", "fr-FR", "zh-Hans-CN"]}
+    )
+    metadata.validate_ui_locales_supported()
+
+    # private use
+    metadata = AuthorizationServerMetadata({"ui_locales_supported": ["x-custom"]})
+    metadata.validate_ui_locales_supported()
+
     # not array
     metadata = AuthorizationServerMetadata({"ui_locales_supported": "en"})
     with pytest.raises(ValueError, match="JSON array"):
         metadata.validate_ui_locales_supported()
 
-    # valid
-    metadata = AuthorizationServerMetadata({"ui_locales_supported": ["en"]})
-    metadata.validate_ui_locales_supported()
+    # underscore instead of hyphen
+    metadata = AuthorizationServerMetadata({"ui_locales_supported": ["fr_FR"]})
+    with pytest.raises(ValueError, match="BCP 47"):
+        metadata.validate_ui_locales_supported()
+
+    # single char (not private-use)
+    metadata = AuthorizationServerMetadata({"ui_locales_supported": ["a-US"]})
+    with pytest.raises(ValueError, match="BCP 47"):
+        metadata.validate_ui_locales_supported()
+
+    # subtag too long
+    metadata = AuthorizationServerMetadata({"ui_locales_supported": ["toolongsubtag"]})
+    with pytest.raises(ValueError, match="BCP 47"):
+        metadata.validate_ui_locales_supported()
 
 
 def test_validate_op_policy_uri():
diff --git a/tests/core/test_oidc/test_core.py b/tests/core/test_oidc/test_core.py
@@ -170,3 +170,17 @@ def test_userinfo_getattribute():
     assert user.email is None
     with pytest.raises(AttributeError):
         user.invalid  # noqa: B018
+
+
+def test_userinfo_validate_locale():
+    UserInfo({"sub": "1"}).validate_locale()
+    UserInfo({"sub": "1", "locale": "en"}).validate_locale()
+    UserInfo({"sub": "1", "locale": "en-US"}).validate_locale()
+    UserInfo({"sub": "1", "locale": "zh-Hans-CN"}).validate_locale()
+    UserInfo({"sub": "1", "locale": "x-custom"}).validate_locale()
+
+    with pytest.raises(ValueError, match="BCP 47"):
+        UserInfo({"sub": "1", "locale": "fr_FR"}).validate_locale()
+
+    with pytest.raises(ValueError, match="BCP 47"):
+        UserInfo({"sub": "1", "locale": "toolongsubtag"}).validate_locale()
diff --git a/tests/core/test_oidc/test_discovery.py b/tests/core/test_oidc/test_discovery.py
@@ -119,6 +119,19 @@ def test_validate_claims_supported():
 def test_validate_claims_locales_supported():
     _call_validate_array("claims_locales_supported", ["en-US"])
 
+    metadata = OpenIDProviderMetadata(
+        {"claims_locales_supported": ["en-US", "fr-FR", "zh-Hans-CN"]}
+    )
+    metadata.validate_claims_locales_supported()
+
+    metadata = OpenIDProviderMetadata({"claims_locales_supported": ["fr_FR"]})
+    with pytest.raises(ValueError, match="BCP 47"):
+        metadata.validate_claims_locales_supported()
+
+    metadata = OpenIDProviderMetadata({"claims_locales_supported": ["toolongsubtag"]})
+    with pytest.raises(ValueError, match="BCP 47"):
+        metadata.validate_claims_locales_supported()
+
 
 def test_validate_claims_parameter_supported():
     _call_validate_boolean("claims_parameter_supported")
