[NEWS] 1 maja 2025 zmienimy sposób kodowania parametru “state” w procesie autoryzacji / On May 1, 2025, we will change the way the “state” parameter is encoded in the authorization process

**1 maja 2025** wprowadzimy zmiany w OAuth dla wszystkich aplikacji korzystających z parametru [state](https://auth0.com/docs/secure/attack-protection/state-parameters).

**Jak to działa obecnie?**

Obecnie serwer Allegro OAuth podczas przekierowania, błędnie obsługuje przekazywanie parametru **state**, który zawiera [znaki zastrzeżone](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2).

Jeśli wysyłasz parametr **state**:

- zakodowany w adresie URL (UTF-8), zawierający znaki zastrzeżone - Allegro OAuth dekoduje część z nich podczas przekierowania,
- ze znakami zastrzeżonymi - Allegro OAuth przekierowuje z częściowo zakodowanym i częściowo zdekodowanym parametrem state. Odszyfrowane znaki to m.in. / lub +, które nie mają żadnego specjalnego znaczenia w komponencie parametrów zapytania.

**Jakie zmiany wprowadzimy?**

**1 maja 2025** zmienimy sposób zwracania parametru **state**:

- zakodowanego w adresie URL (UTF-8) - serwer OAuth zwróci wówczas niezmieniony parametr **state** podczas przekierowania.
- niezakodowanego w adresie URL - przekierujemy użytkownika z zakodowanym parametrem **state** w adresie URL (UTF-8).

Dzięki temu, pomimo różnych form parametru state przekazanych podczas wstępnego żądania autoryzacji, w przekierowaniu będzie on zawsze zakodowany.

**Przykład 1:**

Jeśli Twoja aplikacja wysyła żądanie autoryzacji:

`https://allegro.pl/auth/oauth/authorize?client_id=&redirect_uri=http://127.0.0.1:8000/callback&response_type=code&state=%2Fmy%2Fstate%2F%3D `

**&state=%2Fmy%2Fstate%2F%3D** jest zakodowany w adresie **URL /my/state/=**

serwer autoryzacyjny przekieruje użytkownika po pomyślnym uwierzytelnieniu na adres URL zawierający zakodowany parametr state:

`http://127.0.0.1:8000/callback&code=&state=%2Fmy%2Fstate%2F%3D`

**&state=%2Fmy%2Fstate%2F%3D** - nie zmieniono stanu zakodowanego adresu URL.

**Przykład 2:**

Nie zalecamy przekazywania parametru **state** innego niż zakodowany w adresie URL, ale jeśli Twoja aplikacja wysyła żądanie autoryzacji za pomocą zwykłych znaków zastrzeżonych:

`https://allegro.pl/auth/oauth/authorize?client_id=&redirect_uri=http://127.0.0.1:8000/callback&response_type=code&state=/my/state/=`

**&state=/my/state/=** - niezakodowany w adresie URL.

Przekażemy parametr **state** zakodowany w adresie URL, jak w poniższym przykładzie:

`http://127.0.0.1:8000/callback&code=&state=%2Fmy%2Fstate%2F%3D `

**&state=%2Fmy%2Fstate%2F%3D** - parametr state zakodowany w adresie URL.

**O czym musisz pamiętać?**

1. Upewnij się, że zawsze wysyłasz parametr **state** zawierający [zastrzeżone](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) znaki jako ciąg znaków [zakodowany w adresie URL (UTF-8)](https://www.w3schools.com/tags/ref_urlencode.ASP). Jeśli go nie podasz, dane wyjściowe mogą być mylące, ponieważ będziemy je kodować podczas przekierowania. To samo dotyczy znaków spoza zakresu ASCII: parametr state przekaż jako zakodowany w adresie URL.
2. Upewnij się, że aplikacja kliencka może obsłużyć parametr **state** zakodowany w adresie URL (w formacie UTF-8) podczas przekierowania. Nie zmienimy Twojego początkowego parametru zakodowanego w adresie URL, pod warunkiem, że przekazujesz go w formie zakodowanej.

**Jak możesz to przetestować?**

**Od 1 maja 2025** przestaniemy udostępniać parametr **state** w obecnie częściowo zakodowanej formie. Zaczniemy dostarczać niezmieniony parametr state dla zakodowanych ciągów.

Chcemy jednak dać Tobie możliwość płynnego przejścia na nowe rozwiązanie. Dlatego do tego czasu, dla każdego nowo dodanego adresu **redirect_uri**, udostępnimy niezmieniony parametr state zakodowany w adresie URL. **Twoje stare adresy redirect_uri będą zachowywać się tak jak dotychczas (poprzez częściowe dekodowanie parametrów stanu do 01.05.2025).** Po tym czasie stare adresy URL przekierowań również będą zawierać w pełni zakodowany parametr **state**.

W przypadku wysyłania zakodowanego parametru state ze [znakami zastrzeżonymi](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2):

1. Dodaj nowy redirect_uri, wskazując punkt końcowy w aplikacji, który może obsłużyć zakodowany parametr state.
2. Przetestuj integrację z OAuth dla nowego **redirect_uri**.
3. Zaimplementuj nowy **redirect_uri** na środowisku produkcyjnym. Jeśli stanie się coś złego, możesz to wycofać i nadal używać starego adresu **redirect_uri**, który zachowuje się tak jak dotychczas.
4. Usuń stary adres **redirect_uri**, gdy wszystko będzie już działać zgodnie z oczekiwaniami.

-----------

**On May 1, 2025**, we will make changes to OAuth for all clients using the state parameter.

**How does it work currently?**

Currently, the Allegro OAuth server incorrectly handles the passing of the state parameter, which contains reserved characters, during redirection.

If you send the **state** parameter:

- URL encoded (UTF-8), containing reserved characters - Allegro OAuth decodes some of them during redirection,
- with reserved characters - Allegro OAuth redirects with a partially encoded and partially decoded state parameter. Decoded characters include / or +, which have no special meaning in the query parameter component.

**What changes will we make?**

**On May 1, 2025**, we will change the way the state parameter is returned:

- URL encoded (UTF-8) - the OAuth server will then return the unchanged state parameter during the redirect,
- not URL encoded - we will redirect the user with the URL encoded state parameter (UTF-8).

This way, despite different forms of the **state** parameter passed during the initial authorization request, it will always be encoded in the redirect.

**Example 1:**

If your application sends an authorization request:

`https://allegro.pl/auth/oauth/authorize?client_id=&redirect_uri=http://127.0.0.1:8000/callback&response_type=code&state=%2Fmy%2Fstate%2F%3D`

**&state=%2Fmy%2Fstate%2F%3D** - encoded in the URL address **/my/state/=**

the authorization server will redirect the user after successful authentication to a URL containing the encoded state parameter:

`http://127.0.0.1:8000/callback&code=&state=%2Fmy%2Fstate%2F%3D`

**&state=%2Fmy%2Fstate%2F%3D** - URL encoded state not changed

**Example 2:**

We do not recommend passing a non-URL-encoded state parameter, but if your app sends an authorization request using plain reserved characters:

`https://allegro.pl/auth/oauth/authorize?client_id=&redirect_uri=http://127.0.0.1:8000/callback&response_type=code&state=/my/state/=`

**&state=/my/state/=** - not url encoded

We will pass the state parameter encoded in the URL, as in the example below:

`http://127.0.0.1:8000/callback&code=&state=%2Fmy%2Fstate%2F%3D`

**&state=%2Fmy%2Fstate%2F%3D** - URL encoded state parameter

**What do you need to remember?**

- Make sure to always send the state parameter containing [reserved characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) as a [URL-encoded (UTF-8) string](https://www.w3schools.com/tags/ref_urlencode.ASP). If you don't provide it, the output may be misleading because we'll encode it during the redirect. The same applies to non-ASCII characters: pass the state parameter as URL-encoded.
- Make sure your client application can handle the URL-encoded (UTF-8) state parameter during the redirect. We won't change your initial URL-encoded parameter as long as you pass it in encoded form.

**How can you test it?**

As of **May 1, 2025**, we will stop providing the state parameter in its currently partially encoded form. We will start providing an unchanged state parameter for encoded strings.

However, we want to provide you with a smooth transition. So until then, for any newly added redirect_uri, we will provide an unchanged URL-encoded state parameter. **Your old redirect_uris will continue to behave as before (by partially decoding state parameters until 05/01/2025)**. After that, your old redirect URLs will also contain a fully encoded **state** parameter.

When sending an encoded state parameter with [reserved characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2):

1. Add a new **redirect_uri**, pointing to an endpoint in your app that can handle the hard-coded state parameter.
2. Test the OAuth integration for the new **redirect_uri**.
3. Implement the new redirect_uri in production. If something bad happens, you can roll it back and continue using the old **redirect_uri**, which behaves as before.
4. Delete the old **redirect_uri** once everything is working as expected.