Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

GUACAMOLE-1020: Grammatical corrections and clarifications for auth-restrict documentation. #259

Merged
merged 1 commit into from
Sep 10, 2024
Merged

GUACAMOLE-1020: Grammatical corrections and clarifications for auth-restrict documentation. #259

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 45 additions & 47 deletions src/auth-restrict.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,15 @@ Enforcing Advanced Login and Connection Restrictions

A feature of Guacamole as of version 1.6.0 is an extension that allows you to
enforce advanced restrictions on both user logins to Guacamole as well as the
user of connections and connection groups. The extension,
use of connections and connection groups. The extension,
`guacamole-auth-restrict`, decorates other authentication extensions that
contain user information and/or connections, and allows you to apply
restrictions to those objects for the time(s) that users are allowed or not
allowed to log in, the hosts from which users may or may not log in, the
time(s) that certain connections and balancing connection groups may or
may not be used, and the hosts from which certain connections and
balancing connection groups may or not may not be used. The goal is to
give administrators of a Guacamole system additional flexibility in
restricting when and from where the system can be used.
contain user, group and/or connection information, and allows you to apply
restrictions to those objects for the time(s) that users are allowed to log
in, the hosts from which users may log in, the time(s) that certain
connections and balancing connection groups may be used, and the hosts from
which certain connections and balancing connection groups may be used. The
goal is to give administrators of a Guacamole system additional flexibility in
restricting when and from where various parts of the system may be used.

As this extension decorates underlying extensions, it must be used alongside
one that is capable of storing additional information for users, user groups,
Expand Down Expand Up @@ -71,14 +70,13 @@ There are no guacamole.properties parameters that need to be configured
in order to begin using the auth-restrict extension.

:::{important}
However, because the extension is capable of restricting access to logins
and connections based on the client's IP address, it is important to make
sure that Guacamole is receiving the correct IP address(es) for clients.
This is particularly noteworthy when Guacamole is behind a reverse proxy,
as noted in the [proxying Guacamole](reverse-proxy) manual page, but
administrators should validate any potential network component that may
block or adjust the IP address that Guacamole receives for client
connections.
However, because the extension is capable of restricting access to logins and
connections based on the client's IP address, it is important to make sure
that Guacamole is receiving the correct IP address(es) for clients. This is
particularly noteworthy when Guacamole is behind a reverse proxy, as
documented in the [proxying Guacamole](reverse-proxy) manual page, but
administrators should validate any potential network component that may filter
or modify the IP address that Guacamole receives for client connections.
:::

(completing-auth-restrict-install)=
Expand All @@ -101,8 +99,8 @@ objects within the Guacamole system. The new section of options looks like this:

![](images/auth-restrict-options.png)

The next sections will cover how each restriction impacts the various objects
in the system.
The next sections will cover how each restriction impacts the availability of
various objects in the system.

### User Logins

Expand Down Expand Up @@ -138,7 +136,7 @@ is [more discussion below](how-restrictions-are-processed) on the order in which
rules are processed and which takes precedence.

If a user attempts to log in at a time not allowed by the time-based
restrictions applied to that user, an error will be displayed on the login
restrictions that apply to that user, an error will be displayed on the login
page:

![](images/auth-restrict-login-failed-time.png)
Expand All @@ -148,8 +146,8 @@ page:
Creating restrictions that involve day and time can be tricky when factoring
in the timezones of users, particulary if you have users spread out around
the world. This extension stores the restrictions in UTC, translating them
from the local timezone of the administrator. So, when administering these
restrictions, in important to keep in mind how those restrictions will
from the local timezone of the administrator. When administering these
restrictions it is important to keep in mind how those restrictions will
actually impact users.

Consider the following example that may help to clarify how this works in
Expand All @@ -164,14 +162,14 @@ practice:
between 03:00 PM and 11:00 PM.

This is likely not the behavior that you want, so the restrictions entered for
the users - and connections - should be done with a consideration of where the
the users - and connections - should be done with consideration for where the
users are located and how it will actually apply to those users.

This is further complicated by Daylight Savings Time, which is still observed
in a large portion of the world. As the database stores the restrictions in
UTC, a restriction entered by an administrator in the US Eastern Timezone
during Daylight Savings Time (Summer Time) for 09:00 AM to 05:00 PM will
shift back an hour in the non-DST period, and actually be 08:00 AM to
shift back an hour in the non-DST period, and actually apply from 08:00 AM to
04:00 PM.

#### Restricting logins based on host
Expand All @@ -194,9 +192,9 @@ those hostnames is consistent.
:::

As an example, suppose that you have a group of users that you'd like to
restrict logins such that they can only log in from a specific internal
subnet - let's say 192.168.123.0/24. You would simply put that subnet in the
allowed hosts box, and Guacamole would allow access for users to log in from IP
restrict logins such that they can only log in from a specific internal subnet
- let's say 192.168.123.0/24. You would simply put that subnet in the allowed
hosts box, and Guacamole would allow access for users to log in from IP
addresses within that subnet, but block access from all other subnets:

![](images/auth-restrict-login-local-subnet.png)
Expand Down Expand Up @@ -228,40 +226,40 @@ users and user groups.

First, if restrictions are applied to both users and a user group of which
that user is a member, then the restrictions placed on the user will take
precedence over those on the user group. So, for example, if you deny login at
a certain time to a user group, but add a rule to a member of that group to
precedence over those on the user group. For example, if you deny login at a
certain time to a user group, but add a rule to a member of that group to
allow logins at a time that overlaps with the deny time of the group, the login
will be allowed. Conversely, if you've allowed logins for a group at a
particular time, but you've denied a login for a specific user who is a member
of that group at a given time, the login will be denied. Similar logic applies
to the hosts and/or subnets rules that govern a user's ability to log in.
to the host rules that govern a user's ability to log in.

Second, Guacamole attempts to pull all effective user groups of which a user is
a member and process the restrictions across all of those groups. This
includes nested groups, as well. The caution, here, is to be aware of what
groups you're applying rules on and how those groups relate - if you rely on
complex group nesting within your Guacamole installation, you can quickly
create very complex restriction scenarios that make it difficult to sort out
when a user can log in and when they cannot. Keeping your group nesting as
simple as possible will help avoid these situations.
complex group nesting within your Guacamole installation, you can end up with
very complex restriction scenarios that make it difficult to sort out when a
user can log in and when they cannot. Keeping your group nesting as simple as
possible will help avoid these situations.

### Connections and Connection Groups

This extension allows for the restriction of use of specific connections and/or
This extension allows for the restricting the use of specific connections and/or
connection groups (of the balancing variety) based on the same criteria by
which you can restrict user logins - day/time of week and/or client address.

The examples given above for user logins can be slightly updated to see some
use-cases for connections. For example, you have an application that you
provide access to via Guacamole that you'd like to make sure is only available
during business hours. Or, perhaps, you have a balancing connection group that
you want to make sure is only used by users who are logging in from inside a
certain subnet within your firewall, and not from any public Internet clients.
The user interface for these restrictions for Connections and Connection
Groups is identical to the interface shown above for Users and User Groups.
use-cases for connections. You might host an application through Guacamole that
you'd like to make sure is only available during your normal business hours.
Or, perhaps you have a balancing connection group that you want to make sure
is only used by users who are logging in from a certain subnet within your
firewall, and not from any public Internet clients. The user interface for
these restrictions for Connections and Connection Groups is identical to the
interface shown above for Users and User Groups.

If a restriction applies to a Connection or Connection Group that results
in a user being denied access to a connection, they will receive an error
in access being denied to a connection, the user will receive an error
indicating that they do not have access to the connection:

![](images/auth-restrict-connection-failed.png)
Expand All @@ -279,7 +277,7 @@ processed.
Here are a few key items to keep in mind:

* System administrators are exempt from login restriction rules. If you apply
restrictions to either a specific user or a group, and a user who is a
restrictions to either a specific user or a group, but a user who is a
system administrator attempts to log in, the restrictions will be bypassed
and a warning will be logged to the Guacamole log file.

Expand Down Expand Up @@ -313,9 +311,9 @@ Here are a few key items to keep in mind:
address is a member, the login (or connection) will be denied.

* As mentioned above, individual user rules are processed before, and thus take
precedence over, user group rules. So, if a user is explicitly allowed or
denied, that rule will apply regardless of whether a rule on a group of which
that user is a member would apply.
precedence over, user group rules. If a user is explicitly allowed or denied,
that rule will apply regardless of whether a rule on a group of which that
user is a member would apply.

* Time-based restrictions are processed prior to host-based restrictions, but
both will be taken into account. If a user is configured to be allowed at a
Expand Down
Loading