From 2e9995b0a05ba43a894b50e5f1c71eb3ad777d49 Mon Sep 17 00:00:00 2001 From: Raul Metsma Date: Mon, 25 May 2026 11:18:03 +0300 Subject: [PATCH] Clarify how URL should be encoded WE2-1241 Signed-off-by: Raul Metsma --- README.md | 10 +++++++++- example/README.md | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 54ed071..2c783aa 100644 --- a/README.md +++ b/README.md @@ -181,6 +181,14 @@ return new 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. @@ -334,7 +342,7 @@ The website backend must lookup the challenge nonce from its local store using a As described in section *[5. Configure the authentication token validator](#5-configure-the-authentication-token-validator)*, the mandatory 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://" [ ":" ]` 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://" [ ":" ]` 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 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 detected. Trusted certificate authority certificates configuration is described in more detail in section *[4. Add trusted certificate authority certificates](#4-add-trusted-certificate-authority-certificates)*. diff --git a/example/README.md b/example/README.md index ad41bd2..f81acad 100644 --- a/example/README.md +++ b/example/README.md @@ -65,7 +65,7 @@ To configure the origin URL, add `OriginUrl` field in the application settings f "OriginUrl": "https://example.org" } ``` -Note that the URL **must not end with a slash** `/` and the URL must be the same as the `applicationUrl` in `launchSettings.json`. When you change the `OriginUrl`, also change the `applicationUrl` in `launchSettings.json`. +Note that the URL **must not end with a slash** `/` and the URL must be the same as the `applicationUrl` in `launchSettings.json`. When you change the `OriginUrl`, also change the `applicationUrl` in `launchSettings.json`. For internationalized domain names, use the ASCII/Punycode origin form in `OriginUrl`, for example `https://xn--pike-loa.ee` for `https://päike.ee`. ### 3. Configure the trusted certificate authority certificates