How I concurred CORS and got shlink and shlink-web-client to work - the easy way.

[Lockszmith-GH]

UPDATE 2025-02: TrueChrats does not exist anymore in the way my article used to describe, and I don't use it anymore - the architecture is still solid, and might help you in a non-TrueChart setting - so I'm keeping it here, just updating the article removing references to TrueChart.

I've been struggling with a proper implementation of Shlink-Web-Client on my self-hosted setup of Shlink for some time, until finally everything clicked.

tl;dr: skip to The Solution section at the bottom to skip the whole story.

I might be naive, but I feel this is something other might struggle with, and since the documentation didn't lead me directly to the solution, I thought I'll share my solution.

Goal

• Short URLs accessible via https://example.com/<slug>
• shlink-web-client accessible on https://shlink.example.com
  or^* https://shlink.mydomain.com
  • To keep it safe, (not covered in this post), I have the web-client behind authentik to allow only authorized users access.

Reverse Proxy configuration

The reverse proxy of my choice is Traefik, and in certain situations - like using the TrueNAS SCALE WebUI, there are limitations to the way things can be configured.

Below I describe how I setup the traefik routing:

The basic setup:

• Route host example.com with path / over https to slink service
• Route host shlink.example.com with path / over https to shlink-web-client

The problem

At this point, when accessing https://shlink.example.com I found that adding the shlink server API key pointing at an IP address, internal hostname or external https://example.com would fail the connection when I'm accessing via the reverse-proxy https connection. The following message would show up:

❗ Oops! Could not connect to this Shlink server.
❗ Make sure you have internet connection, and the server is properly configured and on-line.

Inspecting the browser's Developer Tools Console, the following was visible:

Warning Some cookies are misusing the recommended “SameSite“ attribute 2
❗ Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://example.com/rest/v3/health. (Reason: CORS request did not succeed). Status code: (null).

After letting it drive me↗️ nuts, and while I understood what CORS is, I was focused on my inability to modify headers 'easily' within TrueNAS SCALE and I completely missed the solution that now seems very obvious to me.

The solution

• Add a route to the shlink service/app/container from the shlink-web-client hostname shlink.example.com (or^* shlink.mydomain.com) for the /rest/ path.

Then, in the web-client, add the server with https://shlink.example.com (^* https://shlink.mydomain.com).
Because of the /rest/ path pointing to the shlink service's API, there is no Cross-Origin Request, thus not triggering any CORS related issue.

Summary

The three routes that are required, are:

For the shlink BE server, the following ingress definition:
IMPORTANT: no authentication middleware for the main shlink service, that is protected by the API key.

• Host example.com with path /
• Host shlink.example.com (or ^* shlink.mydomain.com) with path /rest/

  This is the 'trick' that makes it work.

For the shlink-web-client FE (the one WITH the authentication middleware):

• Host shlink.example.com (or [<sup>*</sup>](#note-about-authentication-proxy)shlink.mydomain.com) with path /`.

In the Web Client (or the container's envrionment) the server URL would be: https://shlink.example.com (or [<sup>*</sup>](#note-about-authentication-proxy)shlink.mydomain.com), even though it will generate short URLs at https://example.com/...`

* NOTE about authentication proxy:

If your authentication proxy is served from another domain name (let's say auth.mydomain.com), unless it supports multi-domain authorization, your shlink-web-client must use the same domain as the proxy.
This means, that instead of shlink.example.com as described above, you should use shlink.mydomain.com.

[acelaya]

Thanks for sharing!

However, you shouldn't need to do all this, as Shlink handles CORS out of the box.

When this happens it is usually because the proxy in front of Shlink is stripping out the CORS headers. I believe this has been reported in the past by some other people also using traefik.

[Lockszmith-GH]

I know Shlink handles CORS, and you are right, the problem stems from the rigidness of this particular traefik implementation of TrueCharts.
Theoretically, creating a middleware that passes the CORS headers correctly should also resolve this, but it's a more complex solution.

This way, for the case of self-hosting and managing a single shlink server, I not only solve the issue, but also make it 'simple' (albeit superficial). All we need is the /rest access to have the same origin, and routing it like this - should work.

I shared so that others, with the same set of limitations as I have, would find it useful.

I'll also link this to the TrueCharts community, so they can write it in their guides.

[acelaya]

Cool! Thanks again.

[vutsalsinghal]

@Lockszmith-GH very nice! I was in the same boat as you #796 and your solution above worked for my use case too 😄

@acelaya thank you for the amazing project and for all your support!

[vutsalsinghal]

Only downside I can think of this approach (so far) is that if you've multiple backends then which one should /rest point to?

[Lockszmith-GH]

@vutsalsinghal you are right, but then again this issue is unique to situations where there is little control of the reverse-proxy.

If you manage multiple backbends, I would suggest to invest time into figuring out how to properly support CORS headers

[Lockszmith-GH]

You can create multiple hostnames for the same manager, each pointing at a different backend.

[vutsalsinghal]

@Lockszmith-GH actually i went through the docs, and since it supports multiple domains out of the box, you can point 2 domains to same shlink-server backend (just have to take care of the routing aspect in nginx, etc). Its exactly what I wanted. Love the multi-domain support feature!

[SmartPhoneLover]

@Lockszmith-GH
What do you mean by adding a route? Is it related to Traefik?
Add a route to the shlink service/app/container from hostname shlink.example.com for the /rest path

I have a similar issue, but my setup is a bit different:
Here another CORS headache, but with a slightly different setup

[Lockszmith-GH]

That's the trick to make it work inspite of the CORS restriction - the actual short link configuration is in your shlink server, so those will continue to be created correctly.

The REST api endpoint can olny be accessed with the correct API key anyway, and the mapping you're doing is locally anyway, so you're not exposing something more.

[SmartPhoneLover]

Well, thank you for helping me. But I couldn't make it work.

Finally, I decided to use YOURLS. It works like a charm.

Did you force HTTPS for Shlink (backend) with the corresponding env?

[Lockszmith-GH]

Yes, I use all HTTPS, as I expose my shlink web client to the web as well behind an authentication service (I use authentik).
authentik is setup with forward proxy auth and only after authentication can I access my internal tools (like shlink).

If you had shlink-web-client as http and shlink as https, that is another CORS protection that would fail.

[SmartPhoneLover]

I used HTTPS for both services. I mean:

• Shlink (FE): Not exposed, only accessible on my LAN, but with SSL certificates, and HTTPS is configured to FORCED via Nginx Proxy Manager.
• Shlink (BE): Exposed using CF Tunnels, so no reverse proxy was used (mine) on this. HTTPS is forced to ALWAYS on my Cloudflare settings for its base domain and all its subdomains.The 'IS_HTTPS_ENABLED' variable is set to 'true'.

Thank you for your help anyway.

[Lockszmith-GH]

I'm sorry this didn't help, to be clear, I'm not completely clear why your setup affects this.
See if exposing FE and BE will do the trick, the FE is a web app - the only sensitive information (if you do not setup default server creds in the server initialization) is actually in the browser - so you're not really exposing any risk.

[SnippetSpace]

@Lockszmith-GH could you please explain how to do this in the UI of the truecharts deployment template?

I have attempted this in the web server container, where shlink.website.com = shlink web server, and url.website.com = shlink server

then I added shlink.website.com to the webserver config as you state:

no luck, I must be missing something.

Thank you!

[Lockszmith-GH]

Hi @SnippetSpace, I've updated my instructions with summary that consolidates everything to a single place.

Please try to define the /rest/ entrypoint on the main shlink service. Just add an additional Host to the Main Ingress there (and of course remove the /rest/ entry from the shlink-web-client).

So shlink ingress:

• Host: url.website.com, path /
• Host: shlink.website.com, path /rest/

And shlink-web-client ingress:

• Host: shlink.website.com, path /
• Recommended: authentication middleware

Inside the web client, the URL would be:

• https://shlink.website.com

[SnippetSpace]

brilliant, got it to work, that is a much clearer explanation :) thanks so much

[gravelfreeman]

Thank you for your new explanation, I was able to get this to work, finally!

When I'm adding auth middleware (Authelia) on shlink-web-client, I'm getting a 401 Unauthorized error message and Authelia's logs are showing this error;

level=error msg="Target URL does not appear to have a relevant session cookies configuration" error="unable to retrieve session cookie domain provider: no configured session cookie domain matches the url 'https://shlink.***.***/'" method=GET path=/api/verify remote_ip=*** target_url="https://shlink.***.***/"

How were you able to get auth working?

[Lockszmith-GH]

Do you have auth working for other services?
I've followed TrueChart's guide, with some minor changes, I use authResponseHeadersRegex instead of enumerating all the authResponseHeaders.
Here is my traefik middleware defintion:

Address: http://authentik-http.ix-authentik.svc.cluster.local:10230/outpost.goauthentik.io/auth/traefik
authResponseHeadersRegex: ^[Xx]-[Aa]uthentik-

If so, the auth middleware should only be assigned to the FE service's ingress, ie shlink-web-client.

If this isn't helpful, reach out in discord (you should be able to find me in via the TrueCharts server, I am in EST time zoen), I'm sure we can figure it out.

[Lockszmith-GH]

After we troubleshooted the issue in discord, it was resolved.
You're issue was a bit different, because you were using a completely different domain for authentication.
The same concepts and solution apply, just my discription wasn't complte about it, I'll update to include this. I've updated the post. Hope its still clear.

[gravelfreeman]

Again, thank you so much for helping me out!

[ronindesign]

This seems to have worked for me as well. Same context: TrueNAS Scale apps for both Shlink and Shlink web-client using Traefik app for ingress, SSL cert manager (Let's Encrypt).

Just to explicitly reiterate the solution bit for TrueNAS Scale:

• In the shlink TrueNAS app config: ingress host/path should not only include the usual host: myserver.com and path: /, but also a second ingress entry with host: web-client.myserver.com and path: /rest/
• In the shlink-web-client TrueNAS app config: First, change the Server URL (under section Containers > Main Container > Image Environment) from what you would intuitively use (myserver.com) to instead use web-client.myserver.com (this is how we trick the CORS policy; uses the web-client.myserver.com/rest/ ingress path that is set in the first step on the shlink server app; requests to web-client.myserver.com/rest/ are actually routed to myserver.com/rest/ instead.)
• Lastly, in shlink-web-client TrueNAS app config: ingress host/path is just the usual host: web-client.myserver.com and path: /

EDIT: Don't forget: if you've already added your shlink server in the shlink-web-client, you will need to edit the server entry and change the URL to use the web client host, i.e. https://mydomain.com -> https://web-client.mydomain.com, otherwise you'll still get CORS errors since health check request will still be sent to the root domain directly, e.g. https://mydomain.com/rest/v3/health. When working correctly, health check should be sent to https://web-client.mydomain.com/rest/v3/health