Configuring Single Sign-On (SSO) on a Neuron®

From Build 2024-03-21 you can now configure a Neuron® to support Single Sign-On (SSO). This means that users logged in to the Neuron® can use services on other servers that are accessible via reverse proxies on the Neuron®, and that these services can authorize requests based on that first login on the main Neuron®.

To create SSO-services using a Neuron® as the main gateway hosting multiple services behind using reverse proxies, you need to do the following:

1. For each remote service create a session-enabled Reverse Proxy. By enabling proxy sessions, the reverse proxy node will check for current user login in the session, and forward a JWT-token in an Authorization: Bearer HTTP header to underlying services.

2. On the main Neuron® implement either Quick Login, using session mode, which places the user login object in the QuickLoginUser session variable, or a traditional form login, placing the user login variable in the User session variable.

3. On the remote web servers, you get the JWT token from the Authorization: Bearer header. Make sure to validate the JWT token, to make sure malicious actors are unable to inject calls to your web server with fake JWT tokens, pretending to be a user they are not.

4. All links within the remote web service should be relative, not absolute, to avoid problems when navigating the links as seen from the client, that sees the service via the reverse proxy.

From Build 2024-03-22 you have further resources available, to simplify SSO on the Neuron®:

5. If you have a Quick-Login performed, you can transition this into an Agent API Quick Login on the Neuron® seamlessly, if the identity of the user corresponds to an account on the Neuron® itself.

6. You can now use the Agent API to validate and parse JWT tokens issued by the Neuron®. Use this service if you implement a remote web service accessible via a reverse proxy on the Neuron® to validate and parse unrecognized JWT tokens.

7. You can now also initiate a Quick-Login using the Quick-Login REST API directly. For information on how to process Quick-Login URIs, see the tagsign URI scheme.

You can try the SSO capability of the Neuron® here on the Lab-Neuron, by simply logging in to the Community service, and then navigating to the page https://lab.tagroot.io/labproxy/DisplayBearerToken.md. The /labproxy resource is a reverse proxy back to the lab.tagroot.io Neuron® itself, but this time forwarded requests have the additional SSO-information attached in the HTTP header of the requests. The /DisplayBearerToken.md page simply displays the contents it finds (if it fins) in the Authorization: Bearer header. You can compare this request with the output of simply navigating to the same page, but without the proxy: https://lab.tagroot.io/DisplayBearerToken.md.

Note: If you have a normal form-based login in the session, that login takes presedence over an existing Quick-Login when forwarding login-information in a JWT-token to remote services via the reverse proxy.

This article is being written.

#new, #features, #neuron, #architecture, #network

Using the Neuron® as a reverse proxy

From Build 2024-03-21 you can now use the Neuron® as a reverse proxy. Reverse proxies are defined in the gateway.config file. You can edit this file if you are connected to the Neuron® and have administrative privileges (i.e. receive notifications of important events on the Neuron®).

You setup a reverse proxy on the Neuron® by adding a Reverse Proxy node to the Web Server node:

Setup the reverse proxy, by providing the name of the local resource, that will be mapped to the remote web server. The remote domain points to the domain of the remote server. You can optionally add a remote folder if the content in question lies in a special sub-folder on the remote server. You also need to specify if encryption is to be used (i.e. HTTPS) when the Neuron® connectos to the remote web service, or if unecrypted communication is to be used (i.e. HTTP). Also provide the port number to use when connecting to the remote web service.

Note: Important to note here, is the checkbox is the proxy should be session-aware or not. If the reverse proxy is session-aware, it will also have access to the current user session with the Neuron®. If the user is logged in to the Neuron®, the proxy will therefore have access to this login-information. If the proxy finds such user information in the session, it generates a JWT-token for it, and fowards it to the remote web server in an Authorization: Bearer header. This allows the remote service to gain access to this login-information, and base its authorization evaluations on this login, instead of having to force the user to login separately for each remote web service that is being used. You can find more about this, in the article: Configuring Single Sign-On (SSO) on a Neuron®

Once the node has been configured properly, the gateway.config file and data source is updated accordingly.

Note: The reverse proxy is still not activated. You will need to restart the Neuron® for the reverse proxy to become activated.

Note 2: Be careful in your definition of reverse proxies, to avoid creating race conditions and infinite loops. If you want to crash your server, it’s easier to just shut it down.

Note 3: You can test the above reverse proxy, by navigating to https://lab.tagroot.io/labproxy/.

Note 4: Remote services that are to be accessed via a reverse proxy, needs to be developed correctly for this to be possible. The service must avoid use of absolute URIs or URI’s pointing to the remote web servers root folder (i.e. beginning using a / character). The client does not know the service is hosted on multiple web servers, and only sees the URI as provided by the remote web server. If the URI is absolute, or begins with a /, clicking on the link will navigate to a page that is no longer on the reverse proxy (most probably) since the remote web server does not know the local resource name of the reverse proxy. To solve this, always use relative URIs in remote services.

Note 5: On the other hand, a service that is designed not to be user behind a reverse proxy, should use absolute URIs or URIs beginning with a / characters, as this invalidates any future navigation. You can try the https://lab.tagroot.io/google/ reverse proxy, which forwards requests to Google. To solve this, you simply add multiple reverse proxy node definitions in gateway.config, one for each root resource you want to forward to the remote web server.

#new, #neuron, #features, #network, #architecture