diff --git a/source/architecture.rst b/source/architecture.rst index d10768e79..23b5b49e6 100644 --- a/source/architecture.rst +++ b/source/architecture.rst @@ -7,7 +7,7 @@ Below are some diagrams of OnDemand's architecture: #. Overview is a high level visual generated from PowerPoint. #. System context and Container context diagrams below follow the `C4 `_. - model for software diagrams, are more technically detailed and are built using draw.io + model for software diagrams, are more technically detailed and are built using ``draw.io`` #. Request flow diagram is a sequence diagram built using plantuml. Overview diff --git a/source/authentication/dex.rst b/source/authentication/dex.rst index 72a086ca7..2fc9adc07 100644 --- a/source/authentication/dex.rst +++ b/source/authentication/dex.rst @@ -8,7 +8,7 @@ OpenID Connect with Dex Installing OnDemand Dex package ------------------------------- -First the OnDemand yum repos must be enabled, see :ref:`install-software`. +First the OnDemand yum repositories must be enabled, see :ref:`install-software`. Install the ``ondemand-dex`` package: @@ -36,7 +36,7 @@ Requirements: - Git - Make -Build and install the ondemand-dex binary: +Build and install the ``ondemand-dex`` binary: .. code-block:: sh @@ -53,7 +53,7 @@ Add the ``ondemand-dex`` user and group: sudo groupadd -r ondemand-dex sudo useradd -r -d /var/lib/ondemand-dex -g ondemand-dex -s /sbin/nologin -c "OnDemand Dex" ondemand-dex -Get ``ondemand-dex`` repo and install web files and systemd unit file +Get the ``ondemand-dex`` repository and install web files and systemd unit file .. code-block:: sh @@ -120,13 +120,13 @@ Dex Firewall By default when using SSL, Dex will use port ``5554`` for the communication between OnDemand and Dex as well as login interactions with users accessing OnDemand. The port used for non-SSL is ``5556``. The port being used by Dex must be externally accessible. -Firewalld example: +firewalld example: .. code-block:: sh $ sudo firewall-cmd --zone=public --add-port=5554/tcp --permanent $ sudo firewall-cmd --reload -Iptables example: +iptables example: .. code-block:: sh $ sudo iptables -I INPUT -p tcp -m tcp --dport 5554 -j ACCEPT diff --git a/source/authentication/duo-2fa-with-keycloak.rst b/source/authentication/duo-2fa-with-keycloak.rst index 3a99aeba6..c5b8bdc5f 100644 --- a/source/authentication/duo-2fa-with-keycloak.rst +++ b/source/authentication/duo-2fa-with-keycloak.rst @@ -8,7 +8,7 @@ These are the steps to setup two factor authentication with Duo using Keycloak. Install Keycloak Duo SPI -------------------------------------------------- -#. Clone the Keycloak Duo SPI repo +#. Clone the Keycloak Duo SPI repository. .. code:: @@ -50,11 +50,11 @@ Configure Duo SPI -------------------------------------------------- #. Log into your Keycloak instance -#. Choose the realm to configure in upper left corner, eg ``ondemand`` +#. Choose the realm to configure in upper left corner, e.g., ``ondemand`` #. Choose ``Realm Settings`` in the left menu then ``Security Defenses`` tab #. Add ``frame-src https://*.duosecurity.com/ 'self';`` to the beginning of the value for ``Content-Security-Policy`` #. Choose ``Authentication`` in the left menu -#. While on ``Flows`` tab ensure the dropdown for the flow name is ``Browser`` and click ``Copy`` +#. While on ``Flows`` tab ensure the drop-down for the flow name is ``Browser`` and click ``Copy`` #. Name the new flow ``browser-with-duo`` #. For all items below ``Username Password Form`` delete them by choosing ``Actions`` then ``Delete`` #. Choose ``Actions`` for ``Browser-with-duo Forms`` and choose ``Add Execution`` diff --git a/source/authentication/nsf-access.rst b/source/authentication/nsf-access.rst index 662ea9e17..93f221a05 100644 --- a/source/authentication/nsf-access.rst +++ b/source/authentication/nsf-access.rst @@ -4,7 +4,7 @@ NSF ACCESS ---------- If your site is a part of the `National Science Foundation`_'s (NSF) -`ACCESS`_ program (formerley `XSEDE`_) you can use their Identity Provider (IDP) +`ACCESS`_ program (formerly `XSEDE`_) you can use their Identity Provider (IDP) to authenticate users for your Open OnDemand instance. OIDC Client Registration @@ -15,7 +15,7 @@ instance as an Open ID Connect (OIDC) client. ACCESS uses `CILogon`_ to provide a bridge from campus authentication, via the InCommon Federation, to OAuth/OIDC-based research cyberinfrastructure (CI). -Once you've registered your Open OnDemand instance, you can then configure it accordingly. +Once you have registered your Open OnDemand instance, you can then configure it accordingly. Since `ACCESS`_ uses Open ID Connect (OIDC) you can see our :ref:`oidc documentation ` for more details on how to configure Open OnDemand with what CILogon has provided in registering your application. @@ -49,7 +49,7 @@ Shibboleth and InCommon If your campus already runs Shibboleth authentication, you have an alternative to the Open ID Connect configuration above. -The SAML metadata for idp.access-ci.org is published by InCommon and can be downloaded using the +The SAML metadata for ``idp.access-ci.org`` is published by InCommon and can be downloaded using the Metadata Query (MDQ) Service from https://mdq.incommon.org/entities/https%3A%2F%2Faccess-ci.org%2Fidp . Alternatively, you can download the metadata from https://identity.access-ci.org/access-metadata.xml and configure it in a local file. diff --git a/source/authentication/oidc.rst b/source/authentication/oidc.rst index 52c476c54..973e374ce 100644 --- a/source/authentication/oidc.rst +++ b/source/authentication/oidc.rst @@ -12,7 +12,7 @@ The following prerequisites need to be satisfied: .. note:: - The OnDemand repos have the ``mod_auth_openidc`` RPM for RHEL 8 and Rocky 8 that are newer than what the OS provides to make use of some newer features. + The OnDemand repositories have the ``mod_auth_openidc`` RPM for RHEL 8 and Rocky 8 that are newer than what the OS provides to make use of some newer features. The following is an example :program:`ood-portal-generator` configuration file: diff --git a/source/authentication/overview/configure-logout.rst b/source/authentication/overview/configure-logout.rst index 03c513a74..3abd7e832 100644 --- a/source/authentication/overview/configure-logout.rst +++ b/source/authentication/overview/configure-logout.rst @@ -3,9 +3,9 @@ Configure Logout ================ -The logout link on the dashboard is ``/logout``. OnDemand's Apache config has a separate directive to handle ``/logout``, which by default redirects the user to ``/pun/sys/dashboard/logout``, which is a default logout page displayed by the dashboard. Because authentication handled by Apache, this approach enables the logout URL to be changed based on the authentication strategy used. +The logout link on the dashboard is ``/logout``. OnDemand's Apache configuration has a separate directive to handle ``/logout``, which by default redirects the user to ``/pun/sys/dashboard/logout``, which is a default logout page displayed by the dashboard. Because authentication handled by Apache, this approach enables the logout URL to be changed based on the authentication strategy used. -To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOUT/USER"`` in the ood-portal-generator config at ``/etc/ood/config/ood_portal.yml`` and regenerate the config. +To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOUT/USER"`` in the ``ood-portal-generator`` configuration at ``/etc/ood/config/ood_portal.yml`` and regenerate the configuration. .. describe:: logout_redirect (String, null) @@ -20,14 +20,14 @@ To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOU logout_redirect: "/pun/sys/dashboard/logout" Using OpenID Connect Apache module - Redirect to the mod_auth_oidc logout location: + Redirect to the ``mod_auth_oidc`` logout location: .. code-block:: yaml logout_redirect: "/oidc?logout=https%3A%2F%2Fondemand.my-center.edu" Using Shibboleth Apache module - If the Shibboleth IdP server deployed is at idp.my-center.edu, this is an example redirect with mod_auth_shib: + If the Shibboleth IdP server deployed is at ``idp.my-center.edu``, this is an example redirect with ``mod_auth_shib``: .. code-block:: yaml diff --git a/source/authentication/overview/map-user.rst b/source/authentication/overview/map-user.rst index 1a2332659..970e45447 100644 --- a/source/authentication/overview/map-user.rst +++ b/source/authentication/overview/map-user.rst @@ -28,7 +28,7 @@ Both with variations will be discussed here. Remote User ----------- -It's worth discussusing where ``REMOTE_USER`` is coming from. When apache +It's worth discussing where ``REMOTE_USER`` is coming from. When apache has successfully authenticates a request it sets the variable ``REMOTE_USER`` from, well, the remote. @@ -44,8 +44,8 @@ If you're using an OpenID Connect provider you may need to set tells apache how to set ``REMOTE_USER`` from the claim response. -Reguluar Expression User Mapping --------------------------------- +Regular Expression User Mapping +------------------------------- The simplest and fastest way to map a ``REMOTE_USER`` to a system user is through :ref:`user_map_match `. It isn't directly @@ -57,7 +57,7 @@ Dex Automatic Configuration When using the OpenId Connector `dex`_ and setting `oidc_remote_user_claim`_ to ``email`` we automatically set `user_map_match`_ to ``^([^@]+)@.*$`` as -a convienience. +a convenience. User Map Command for Advanced Mappings -------------------------------------- @@ -74,12 +74,12 @@ configuration and be sure to make this mapping script executable. Be aware, this script is executed on every request. Let's take a simple example. It uses bash's builtin regular expression matching -against ``([^@]+)@osc.edu`` - an osc dot edu email address. If that matches against -``$1`` (the ``REMOTE_USER``) after it's url-decoded, then we return an all lowercase +against ``([^@]+)@osc.edu`` - an ``osc.edu`` email address. If that matches against +``$1`` (the ``REMOTE_USER``) after it's URL decoded, then we return an all lowercase version of the first part of an email address. -The contract this script has with ood is that ``REMOTE_USER`` is url-encoded and -passed into it as the first arguement, ``$1``. +The contract this script has with Open OnDemand is that ``REMOTE_USER`` is URL encoded and +passed into it as the first argument, ``$1``. The script will return 0 and output the match if it can correctly map the user. Otherwise, if it fails, it will output nothing and exit 1. diff --git a/source/authentication/shibboleth.rst b/source/authentication/shibboleth.rst index 3cdcc968c..809956959 100644 --- a/source/authentication/shibboleth.rst +++ b/source/authentication/shibboleth.rst @@ -8,12 +8,12 @@ The following prerequisites need to be satisfied: - A Shibboleth IdP server deployed, e.g., ``idp.my-center.edu`` (outside of scope of this document) - The `Apache module for Shibboleth`_ installed on the OnDemand Server and - properly configured with its own Apache config (outside of scope of this + properly configured with its own Apache configuration (outside of scope of this document) .. warning:: - It is required you turn on ``ShibCompatValidUser`` in your Apache config + It is required you turn on ``ShibCompatValidUser`` in your Apache configuration when setting up the Shibboleth module for Apache above. .. code-block:: apache diff --git a/source/authentication/tutorial-oidc-keycloak-rhel7/add-custom-theme.rst b/source/authentication/tutorial-oidc-keycloak-rhel7/add-custom-theme.rst index 73eded32e..893bcbe31 100644 --- a/source/authentication/tutorial-oidc-keycloak-rhel7/add-custom-theme.rst +++ b/source/authentication/tutorial-oidc-keycloak-rhel7/add-custom-theme.rst @@ -28,9 +28,3 @@ Here are two links to get started with a custom theme: Remember after adding a theme you still need to configure your realm in the Keycloak admin UI to use the theme for the login pages. -.. note:: - - Soon we will offer an ood-keycloak base theme that be easier to extended to - provide most of the common themeing a site might like to perform. It will - also work well for OTP views. - diff --git a/source/installation/modify-system-security.rst b/source/installation/modify-system-security.rst index e2a157b83..eb7443fb9 100644 --- a/source/installation/modify-system-security.rst +++ b/source/installation/modify-system-security.rst @@ -68,19 +68,19 @@ After OnDemand updates that include the ``ondemand-selinux`` package, some SELin .. _firewall: -Firewall +firewalld --------- #. Open ports 80 (http) and 443 (https) in the firewall, typically done with `firewalld`_ or `iptables`_. - Firewalld example: + firewalld example: .. code-block:: sh $ sudo firewall-cmd --zone=public --add-port=80/tcp --permanent $ sudo firewall-cmd --zone=public --add-port=443/tcp --permanent $ sudo firewall-cmd --reload - Iptables example: + iptables example: .. code-block:: sh $ sudo iptables -I INPUT -p tcp -m tcp --dport 80 -j ACCEPT diff --git a/source/spelling_wordlist.txt b/source/spelling_wordlist.txt index e84d503c3..9f9527c18 100644 --- a/source/spelling_wordlist.txt +++ b/source/spelling_wordlist.txt @@ -31,3 +31,17 @@ SSL Keycloak apache mapfile +ondemand +gRPC +firewalld +expirations +iptables +OAuth +OIDC +cyberinfrastructure +Dex +frontend +backend +IdP +proxied +selectable