Clarify how URL should be encoded

WE2-1241

Signed-off-by: Raul Metsma <raul@metsma.ee>

Author: metsma

README.md

@@ -134,6 +134,14 @@ import eu.webeid.security.validator.AuthTokenValidatorBuilder;
 ...
 ```
 
+The site origin configured with `withSiteOrigin()` must match the origin string
+signed by the Web eID application. Use the [ASCII serialization of the
+origin](https://html.spec.whatwg.org/multipage/browsers.html#ascii-serialisation-of-an-origin)
+as specified by the [Web eID architecture
+document](https://github.com/web-eid/web-eid-system-architecture-doc#web-eid-authentication-token-specification).
+For internationalized domain names, configure the Punycode form, for example
+`https://xn--pike-loa.ee` for `https://päike.ee`.
+
 ## 6. Add a REST endpoint for issuing challenge nonces
 
 A REST endpoint that issues challenge nonces is required for authentication. The endpoint must support `GET` requests.
@@ -262,7 +270,7 @@ The website back end must lookup the challenge nonce from its local store using
 
 As described in section *[5. Configure the authentication token validator](#5-configure-the-authentication-token-validator)*, the mandatory authentication token validator configuration parameters are the website origin and trusted certificate authorities.
 
-**Origin** must be the URL serving the web application. Origin URL must be in the form of `"https://" <hostname> [ ":" <port> ]`  as defined in [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location/origin) and not contain path or query components. **Note that the `origin` URL must not end with a slash `/`**.
+**Origin** must be the URL serving the web application. Origin URL must be in the form of `"https://" <hostname> [ ":" <port> ]`  as defined in [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Location/origin) and not contain path or query components. **Note that the `origin` URL must not end with a slash `/`**. The configured origin must use the ASCII serialization that is signed by the Web eID application. For internationalized domain names, use the Punycode form, for example `https://xn--pike-loa.ee` instead of `https://päike.ee`.
 
 The **trusted certificate authority certificates** are used to validate that the user certificate from the authentication token and the OCSP responder certificate is signed by a trusted certificate authority. Intermediate CA certificates must be used instead of the root CA certificates so that revoked CA certificates can be removed. Trusted certificate authority certificates configuration is described in more detail in section *[4. Add trusted certificate authority certificates](#4-add-trusted-certificate-authority-certificates)*.
 

example/README.md

@@ -33,7 +33,9 @@ web-eid-auth-token:
         local-origin: "https://<<NGROK HOSTNAME HERE>>"
 ```
 
-**Note that the origin URL must not end with a slash `/`**.
+**Note that the origin URL must not end with a slash `/`**. For internationalized
+domain names, use the ASCII/Punycode origin form in `local-origin`, for example
+`https://xn--pike-loa.ee` for `https://päike.ee`.
 
 ### 3. Configure the trusted certificate authority certificates
 
@@ -262,4 +264,3 @@ When running the application with the `dev` profile in test mode, you need to up
 ### Why do I get the `401 Unauthorized "Authentication failed: Web eID token validation failed"` response during authentication?
 
 One possible reason is that you are using the test ID card on a site that is running in production mode or, vice-versa, a real ID card on a site that is running in test mode; or any other ID card whose certificate authority has not been added to the list of trusted certificate authorities. There will be a `CertificateNotTrustedException` in the logs in this case.
-