Server Authentication

Proxy Authentication via Server Auth

Summary

Server Authentication will allow you to secure any/all location blocks at your web server/proxy level, only allowing authenticated Organizr users or administrators access. The result of enabling this feature will disallow users from going to https://domain.com/sonarr directly without authenticating with Organizr first.

Note that this method will only provide an Authorization layer but will not actually pass any Authentication information / credentials to the underlying back-end services, since this would require some cooperation from these services to understand it. So these services will still be accessed as a guest / unauthenticated user, but this is often good enough for many services.

For more information regarding the differences between Authorization vs Authentication, check out this website: https://www.geeksforgeeks.org/difference-between-authentication-and-authorization/

Certain providers block wildcard cookies from being set which prevents this from working with subdomains. The most common of these is DuckDNS. For a full list see the bottom of this page.

Methodology

There are two methods you may use to enable authorization, via the Organizr authorization API or using OAuth / JWT tokens.

The Organizr authorization API method has the drawback of making calls to Organizr's authorization API for each and every HTTP request made against your protected location blocks, therefore impacting performance.

The Oauth / JWT Token method allows you to securely trust the Organizr authentication simply based on the JWT token passed in your authenticated requests cookies. It does not require any extra roundtrip to the Organizr API, nor the rewrite directives.

Using the Organizr authorization API method

To utilize the block add auth_request /organizr-auth/$; See table below:

$	Organizr group_id
0	Admin
1	Co-Admin
2	Super User
3	Power User
4	User
5-997	Custom Groups
998	Any logged in user
999	Guest

For this to work, a URL rewrite directive needs to be added so that the static /organizr-auth/$ locations can be understood by Organizr's authentication API, i.e. use the /api/v2/auth/$1 format. You may find instructions and examples for Nginx, Caddy, and Traefik on subpages in this documentation.

Using the OAuth / JWT token method

The first method has the drawback of making calls to Organizr's authorization API for each and every HTTP request made against your protected location blocks, therefore impacting performance.

This method allows you to securely trust the Organizr authentication simply based on the JWT token passed in your authenticated requests cookies. It does not require any extra roundtrip to the Organizr API, nor the rewrite directives.

The flow is as follows:

1. An unauthenticated user accesses Organizr UI and logs in, using any of the supported login methods.

2. After successful login, the browser will keep an authentication cookie generated by Organizr using the standard JSON Web Token (JWT) format. This signed token includes a number of claims (such as user id, group memberships etc) that the user has. For more info on this standard, visit https://jwt.io/

3. This cookie is then passed to any subsequent visit to your Organizr domain and subdomains.

4. Capable web servers can easily read the JWT token from this cookie and validate it to trust the user's identity and make an allow/deny decision based on the claims mentioned in the token.

Organizr JWT token structure

You can easily check the contents of Organizr-generated JWT tokens by inspecting your browser cookies and pasting the contents of the cookie named organizr_token_<uuid> to a JWT inspector such as https://jwt.io/

Once decoded, an Organizr token includes a JWT payload similar to this:

{
  "iss": "Organizr",
  "aud": "Organizr",
  "jti": "4f1g23a12aa",
  "iat": 1555553579,
  "exp": 1556158379,
  "username": "myusername",
  "group": "Admin",
  "groupID": 0,
  "email": "[email protected]",
  "image": "https://www.gravatar.com/avatar/901d703edb7a7f21a92ae87f29484d01?s=100&d=mm",
  "userID": 1
}

It includes various claims such as your user name, group name, user id, group id, which can all be used by your JWT-aware web server to make an authorization decision.

Validating the token

Of course, your web server should not blindly trust the content of the JWT token since it cold have been forged. In order to trust the token content, your web server will need to validate its signature. This requires the server to know a secret specific to your Organizr instance.

Since Organizr uses HS256 signature algorithm, which is a symmetric algorithm, the same secret is used to both by Organizr to sign the token, and by your web server to validate it. It is therefore important that you keep this secret safe, otherwise it may be used to forge tokens and authenticate to your server!

This requires the following 2 pieces of information:

• The name of the cookie to use to extract the token from. This value is dynamic, of the form organizr_token_<uuid> where <uuid> is your Organizr instance's $this->config['uuid'] value.

• The secret to use to validate the token signature, which is your Organizr instance's $this->config['organizrHash'] value.

Both these values can be taken from your Organizr server's www/Dashboard/api/config/config.php after initial setup.

On Linux, you may use the following commands to parse them:

cat /config/www/Dashboard/api/config/config.php  | grep organizrHash | sed -r 's/.*=>[^[:alnum:]]*([[:alnum:]]*).*/\1/'
cat /config/www/Dashboard/api/config/config.php  | grep uuid | sed -r 's/.*=>[^[:alnum:]]*([[:alnum:]-]*).*/\1/'

Providers that block wildcard cookies

ddns.net
ddnsking.com
3utilities.com
bounceme.net
duckdns.org
freedynamicdns.net
freedynamicdns.org
gotdns.ch
hopto.org
myddns.me
myds.me
myftp.biz
myftp.org
myvnc.com
noip.com
onthewifi.com
redirectme.net
serveblog.net
servecounterstrike.com
serveftp.com
servegame.com
servehalflife.com
servehttp.com
serveirc.com
serveminecraft.net
servemp3.com
servepics.com
servequake.com
sytes.net
viewdns.net
webhop.me
zapto.org