Authentik: Single Sign-On Configuration for Paperless-ngx

Preparation

For the purpose of preparing the tutorial, we will adopt the domain names and identifiers described below. During setup, adjust the settings according to your needs.

• Full domain name (FQDN) of Paperless-ngx: https://paperless.xyz.com
• Full domain name (FQDN) Portainer: https://auth.xyz.com

What is OpenID Connect?

The OpenID Connect (OIDC) protocol is an authentication layer based on the OAuth 2.0 protocol that enables secure authentication and acquisition of user identity information in web applications. Below are the key elements that describe how OpenID Connect works:

• OAuth 2.0 authentication: OpenID Connect uses the OAuth 2.0 protocol as the basis for authentication. OAuth 2.0 allows applications to access resources on behalf of the user, and OpenID Connect extends this protocol with an authentication layer.
• Issuing Tokens: Once a user is successfully authenticated, its gets tokens that contain identity information. These are typically:
  • ID Token: Contains basic information about the user, such as ID, first name, last name, etc.
  • Access Token: Allows access to protected resources on behalf of the user.
  • Refresh Token: It is used to refresh or obtain new tokens after expiration.
• JSON Web Tokens (JWT): The information sent in the tokens is often encoded in the JSON form of Web Tokens, which keeps them concise and secure.
• End-User Authentication: OpenID Connect supports various methods of user authentication, such as password login, multi-factor authentication or even third-party identity providers.
• Configuration Information: The identifiers and information necessary to authorize and receive tokens are obtained from the configuration document, which is usually available at a fixed URL.
• Security over TLS: Communication between the client and the identity provider, as well as between the provider and the resource server, should take place over a secure TLS (HTTPS) connection.

In summary, OpenID Connect facilitates secure and efficient authentication of users in web applications, while allowing users to acquire their identity information through tokens.

Operation of OpenID Connect

The process of the OpenID Connect (OIDC) protocol can be divided into several steps. Below you will find a general description of the steps involved in this process:

• Initiate Authorization Request:
  • The user wants to log into the application, supporting OpenID Connect.
  • The application directs it to the identity provider (IdP) with an authorization request.
  • This request contains the ranges (scopes) of access that the application wants, and information about what actions are required after the authorization is completed.
• User Authentication (Authentication):
  • The identity provider authorizes the user.
  • If the user is not logged in, they may be asked for their credentials.
• Redirection Back:
  • Once the user is successfully authenticated, the identity provider redirects the user back to the application while providing an authorization code.
• Code-to-Token Exchange (Token Exchange):
  • The application sends the received authorization code back to the identity provider.
  • In return, it receives a set of tokens, such as an ID Token, Access Token and possibly a Refresh Token.
• Use of Tokens (Access Resources):
  • The application uses the received Access Token to access protected resources on behalf of the user.
  • Access to resources can be limited by the access range specified in the token.
• Token Verification:
  • The application verifies the validity of the received tokens, especially the ID Token, which contains information about the user’s identity.
  • Verification may include checking the token’s signature, its validity and compliance with authorization requests.
• Token Refresh:
  • If Refresh Token is used, the application can refresh its tokens without having to re-authenticate the user.

Step 1 – Install Paperless-ngx on Synology

Wondering how to install Paperless-ngx on a Synology server? Step 1 is the foundation that will bring you closer to achieving this goal. Learn how to set up your environment and start using advanced paperless document management. I invite you to read my latest article, where I explain step by step how to do it.

👉 Go to the instructions and start transforming your documents today!

Step 2 – Configure Nginx Proxy Manager in the Portainer

Before you start implementing Single Sign-On on Synology with Paperless-ngx, make sure your Nginx Proxy Manager is configured. Not sure how to do it? Take it easy! In my latest article, you’ll find a quick step-by-step guide on how to do this using Docker Compose in the Porter.

👉 Check out step 2 now and get your environment ready for more reinforcements!

Step 3 – Configure Single Sign-On in the Portainer

Do you already know how to make logging into Portainer simultaneous and seamless with Single Sign-On? If not, it’s time to change that! In my latest step-by-step tutorial, you’ll learn how to set up SSO using Authentik and Portainer.

👉 Visit step 3 now and get easier access to your Docker environment!

Step 3 – Configuration in Authentik

Previous configuration based on HTTP header

If you were previously using single sign-on in Paperless-ngx via HTTP header and want to switch to OpenID Connect, follow these steps:

• Remove the previous configuration from Authentik by Proxy Provider and reconfigure according to the instructions for OpenID Connect
• For Reverse Proxy users, e.g. Nginx Proxy Manager: replace in Proxy Hosts the port that redirected to Authentik (as Proxy Provider), with the port corresponding to the one you configured earlier (e.g. 8777).
• In Docker Compose, remove the specific parameters associated with the previous authorization method and save the new configuration.