diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 10d1f2e..99a1459 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -1,5 +1,5 @@ --- -description: How to contribute to Bifröst technically and which guidelines are in place. +description: >Technical contributions to Bifröst and corresponding guidelines. --- # Contributing Guidelines @@ -15,14 +15,14 @@ Any kind of contribution is welcome, from adding new features or bug fixes to im ### Technical Requirements -When submitting a PR, make sure that it: +When submitting a Pull Request ("PR"), make sure that it: - Must pass CI jobs/actions. - Must follow [Golang best practices](https://go.dev/doc/effective_go). - Is signed off with the line `Signed-off-by: `. [Learn more about signing off on commits](https://docs.github.com/en/organizations/managing-organization-settings/managing-the-commit-signoff-policy-for-your-organization). - !!! note - Signing off on a commit is different from signing a commit, such as with a GPG key. + !!! Note + Signing-off a commit is different from signing a commit, such as with a GPG key. ### PR Approval @@ -33,11 +33,11 @@ When submitting a PR, make sure that it: #### Schedule -There are no fixed cycles for releases. Currently, they are triggered as soon bugfixes, security updates or main features arrive. +There are no fixed cycles for releases. Currently, they are triggered as soon as bugfixes, security updates or main features arrive. #### Creation -First of all prepare the release notes as usual and merge them. +First of all, prepare the release notes as usual and merge them. Once the release notes are ready, a release train is launched by *tagging* from `main` to `vX.Y.Z`. diff --git a/docs/community/index.md b/docs/community/index.md index 9ec1a54..d6eda14 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -6,11 +6,11 @@ description: Read here all about how to become a member of Bifröst's community. You are a part of making Bifröst great. Thank you! 💪 -To be part of this community be sure you read our [Contributor Covenant Code of Conduct](code-of-conduct.md). +To be part of this community, be sure you read our [Contributor Covenant Code of Conduct](code-of-conduct.md). ## Discussions -We're using [GitHub Discussion](https://github.com/engity-com/bifroest/discussions) for conversations about how to use Bifröst, exchanging ideas, do announcements and much more. +We're using [GitHub Discussion](https://github.com/engity-com/bifroest/discussions) for conversations about how to use Bifröst, for exchanging ideas, for doing announcements and much more. * [See existing topics.](https://github.com/engity-com/bifroest/discussions) * [Start a new topic.](https://github.com/engity-com/bifroest/discussions/new/choose) diff --git a/docs/reference/authorization/htpasswd.md b/docs/reference/authorization/htpasswd.md index 6115405..bc567cf 100644 --- a/docs/reference/authorization/htpasswd.md +++ b/docs/reference/authorization/htpasswd.md @@ -1,11 +1,11 @@ --- toc_depth: 3 -description: How to authorize a requesting user via credentials stored in htpasswd format with Bifröst. +description: How to authorize an user request via credentials stored in htpasswd format with Bifröst. --- # Htpasswd authorization -Authorizes a requesting user via credentials stored in [htpasswd format](#format). +Authorizes an user request via credentials stored in [htpasswd format](#format). ## Properties @@ -41,7 +41,7 @@ authorization: ## Format -htpasswd is a format created for [Apache HTTP Server](https://httpd.apache.org/) to enable an easy way to configure [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) for web servers. Nowadays it is used in more web server projects than just the Apache HTTP Server and also in other project type like Bifröst. The reason: There is a huge toolset available to create those files. +htpasswd is a format created for [Apache HTTP Server](https://httpd.apache.org/) to enable an easy way to configure [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) for web servers. Nowadays, it is used in more web server projects than just the Apache HTTP Server and also in other project types like Bifröst. The reason: There is a huge toolset available to create those files. ## Tools diff --git a/docs/reference/authorization/index.md b/docs/reference/authorization/index.md index c63818b..4e37e4b 100644 --- a/docs/reference/authorization/index.md +++ b/docs/reference/authorization/index.md @@ -4,7 +4,7 @@ description: Everything in Bifröst starts here. A user must be authorized at fi # Authorizations -Everything in Bifröst starts here. A user must be authorized at first. Bifröst supports [different types of authorizations](#types) you can choose from to adjust to your needs. +Everything in Bifröst starts here. Firstly, a user must be authorized. Bifröst supports [different types of authorizations](#types) you can choose from to adjust to your needs. ## Types diff --git a/docs/reference/authorization/local.md b/docs/reference/authorization/local.md index 03cf028..be61185 100644 --- a/docs/reference/authorization/local.md +++ b/docs/reference/authorization/local.md @@ -1,12 +1,12 @@ --- toc_depth: 4 -description: How to authorize a requesting user via the local user database of the host on which Bifröst is running on. +description: How to authorize an user request via the local user database of the host on which Bifröst is running on. --- # Local authorization -Authorizes a requesting user via the local user database of the host on which Bifröst is running on. +Authorizes a user request via the local user database of the host on which Bifröst is running. -!!! note +!!! Note This authorization requires Bifröst to run with root permissions. ## Properties @@ -15,13 +15,13 @@ Authorizes a requesting user via the local user database of the host on which Bi Has to be set to `local` to enable the local authorization. <> -Contains files of the format of classic [authorized keys](../data-type.md#authorized-keys) Bifröst will look in for [SSH Public Keys](../data-type.md#ssh-public-key) . +Contains files with the format of classic [authorized keys](../data-type.md#authorized-keys), in which Bifröst will look for [SSH Public Keys](../data-type.md#ssh-public-key). <> -Contains files of the format of classic [authorized keys](../data-type.md#authorized-keys) Bifröst will look in for [SSH Public Keys](../data-type.md#ssh-public-key) . +Contains files of with format of classic [authorized keys](../data-type.md#authorized-keys), in which Bifröst will look for [SSH Public Keys](../data-type.md#ssh-public-key). <> -If set to a non-empty value, this [PAM](https://wiki.archlinux.org/title/PAM) service will be used during the authorization process instead of `/etc/passwd` and `/etc/shadow` directly. +If set to a non-empty value, this [PAM](https://wiki.archlinux.org/title/PAM) service will be directly used during the authorization process instead of `/etc/passwd` and `/etc/shadow`. ##### Default settings @@ -35,7 +35,7 @@ The password can either be validated via `/etc/passwd` and `/etc/shadow` (defaul ### Support of yescrypt {. #password-yescrypt} -[yescrypt](https://en.wikipedia.org/wiki/Yescrypt) is cryptographic key derivation function used for password hashing in some modern Linux distributions (such as Ubuntu). Their support and give Bifröst the possibility to evaluate their passwords, the [`linux`/`extended` edition](../../setup/distribution.md#linux-extended) of Bifröst is required. +[yescrypt](https://en.wikipedia.org/wiki/Yescrypt) is a cryptographic key derivation function used for password hashing in some modern Linux distributions (such as Ubuntu). Their support gives Bifröst the possibility to evaluate their passwords, the [`linux`/`extended` edition](../../setup/distribution.md#linux-extended) of Bifröst is required. ### Properties {. #password-properties} @@ -46,9 +46,9 @@ If `true`, the user is allowed to use passwords via classic password authenticat If `true`, the user is allowed to use passwords via interactive authentication. <> -If `true`, the user is allowed to use empty password. +If `true`, the user is allowed to use empty passwords. -!!! warning +!!! Warning This is explicitly not recommend. ## Context diff --git a/docs/reference/authorization/oidc.md b/docs/reference/authorization/oidc.md index 89a90bb..9ff359c 100644 --- a/docs/reference/authorization/oidc.md +++ b/docs/reference/authorization/oidc.md @@ -1,12 +1,12 @@ --- toc_depth: 4 -description: How to authorize a requesting user via OpenID Connect (OIDC) with Bifröst. +description: How to authorize a user request via OpenID Connect (OIDC) with Bifröst. --- # OpenID Connect (OIDC) authorization -Authorizes a requesting user via [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/). +Authorizes a user request via [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/). -There is no need that the actual user exists in any way on the host machine of Bifröst. Even if the [local environment](../environment/local.md) is used together with [`createIfAbsent`](../environment/local.md#linux-property-createIfAbsent-evaluation) and [`updateIfDifferent`](../environment/local.md#linux-property-updateIfDifferent-evaluation) set to `true` it will create/update the users. There is no need for tools like Puppet or Ansible. +There is no need that the actual user exists in any way on the host machine of Bifröst. Even if the [local environment](../environment/local.md) is used together with [`createIfAbsent`](../environment/local.md#linux-property-createIfAbsent-evaluation) and [`updateIfDifferent`](../environment/local.md#linux-property-updateIfDifferent-evaluation) set to `true`, it will create/update the users. There is no need for tools like Puppet or Ansible. This provides an easy way for SSO in all types of organizations, small or big. See [use cases for more details](../../usecases.md). diff --git a/docs/reference/authorization/simple.md b/docs/reference/authorization/simple.md index 2e5ca63..a3cd4eb 100644 --- a/docs/reference/authorization/simple.md +++ b/docs/reference/authorization/simple.md @@ -5,7 +5,7 @@ description: How to authorize a requesting user the simplest way with Bifröst. # Simple authorization -Authorizes a requesting user via stored credentials. +Authorizes a user request via stored credentials. ## Properties @@ -13,7 +13,7 @@ Authorizes a requesting user via stored credentials. Has to be set to `simple` to enable simple authorization. <> -Each entry will be inspected to try to authorize a remote user. +Each entry will be inspected to check if a remote user should be authorized. ## Entry @@ -37,7 +37,7 @@ Contains [SSH Public Keys](../data-type.md#ssh-public-key) in the format of clas Similar to [`authorizedKeys`](#entry-property-authorizedKeys), but in a dedicated file. <> -Password (if user uses interactive or password authentication methods) to be evaluated against. +Password (if user uses interactive or password authentication method) to be evaluated against. ## Context diff --git a/docs/reference/connection/ssh.md b/docs/reference/connection/ssh.md index a3810d4..a7b4dce 100644 --- a/docs/reference/connection/ssh.md +++ b/docs/reference/connection/ssh.md @@ -68,7 +68,7 @@ Restrict which ED25519 keys are allowed to be used. <> -Banner which will be shown if the connection was based on an authentication method (like OIDC) which does not have its own public key authentication. At this point the authentication was successful AND the client submitted at least one public key (as authentication try). This key will be used and this message will be shown to the client to inform, that this key will be used for the session from now on. As a result, the original authentication will be skipped (like OIDC) as long as it is not expired and the client presents the same public key. +Banner which will be shown if the connection was based on an authentication method (like OIDC) which does not have its own public key authentication. At this point, the authentication was successful AND the client submitted at least one public key (as authentication try). This key will be used and this message will be shown to the client to inform that this key will be used for the session from now on. As a result, the original authentication will be skipped (like OIDC) as long as it is not expired and the client presents the same public key. ### Examples diff --git a/docs/reference/context/authorization.md b/docs/reference/context/authorization.md index 9d2264e..c16dbb8 100644 --- a/docs/reference/context/authorization.md +++ b/docs/reference/context/authorization.md @@ -6,7 +6,7 @@ description: How to access context information about an authorized user with Bif Represents a fully authorized connection of a user. -There are more specialized variants of the authorization available, based which authorization type was used: +There are more specialized variants of the authorization available, based on which authorization type was used: | Variant | Authorization | |--------------------------------|---------------------------------------------------| diff --git a/docs/reference/context/oidc-id-token.md b/docs/reference/context/oidc-id-token.md index 20d74a7..3766348 100644 --- a/docs/reference/context/oidc-id-token.md +++ b/docs/reference/context/oidc-id-token.md @@ -22,7 +22,7 @@ Holds the `sub` property of the [ID Token](https://openid.net/specs/openid-conne <> -Date when this token will be expired. You will never get a token where this value is in the past. +Date when this token will expire. You will never get a token where this value is in the past. <> diff --git a/docs/reference/context/oidc-user-info.md b/docs/reference/context/oidc-user-info.md index cbe0586..d1c4af9 100644 --- a/docs/reference/context/oidc-user-info.md +++ b/docs/reference/context/oidc-user-info.md @@ -4,7 +4,7 @@ description: How to access context information about a user's UserInfo of its su # Context OpenID Connect (OIDC) UserInfo -Holds the full user information about a user who was authorized via [OIDC](../authorization/oidc.md), if configured and available. +Holds the full user information about a user who was authorized via [OIDC](../authorization/oidc.md), if configured and if available. ## Properties diff --git a/docs/reference/environment/local.md b/docs/reference/environment/local.md index 4db810f..8a4ab14 100644 --- a/docs/reference/environment/local.md +++ b/docs/reference/environment/local.md @@ -5,7 +5,7 @@ toc_depth: 4 # Local environment -A Local environment is executed on the host itself (same host where Bifröst is running). +A local environment is executed on the host itself (same host where Bifröst is running). Currently, we support different variants provided by the host operating system which is executing the environment. @@ -17,14 +17,14 @@ The Linux variant is only supported by Linux based operating systems. It can run as the Bifröst user itself, but can also [impersonate](https://en.wiktionary.org/wiki/impersonate) another user. -!!! note - If impersonating another user Bifröst than is running at, root permissions are required. +!!! Note + If impersonating another user Bifröst is running at, root permissions are required. ### User requirement {: #linux-user-requirement} Users have to fulfill the defined requirements ([`name`](#linux-property-name), [`displayName`](#linux-property-displayName), [`uid`](#linux-property-uid), [`group`](#linux-property-group), [`groups`](#linux-property-groups), [`shell`](#linux-property-shell), [`homeDir`](#linux-property-homeDir) and [`skel`](#linux-property-skel)). -If a user does not fulfill this requirement he is not eligible for the environment. The environment **can** create a user ([`createIfAbsent`](#linux-property-createIfAbsent) = `true`) or even update an existing one ([`updateIfDifferent`](#linux-property-updateIfDifferent) = `true`) to match this requirement. This does not make a lot of sense for [local users](../authorization/local.md); but for [users authorized via OIDC](../authorization/oidc.md) - which usually do not exist locally. +If a user does not fulfill this requirement they are not eligible for the environment. The environment **can** creates a user ([`createIfAbsent`](#linux-property-createIfAbsent) = `true`) or even updates an existing one ([`updateIfDifferent`](#linux-property-updateIfDifferent) = `true`) to match this requirement. This does not make a lot of sense for [local users](../authorization/local.md); but for [users authorized via OIDC](../authorization/oidc.md) - which usually do not exist locally. See the evaluation matrix of [`createIfAbsent`](#linux-property-createIfAbsent-evaluation) and [`updateIfDifferent`](#linux-property-updateIfDifferent-evaluation) to see the actual reactions of the local environment per users requirement evaluation state. @@ -124,13 +124,13 @@ The groups (do not confuse with the [primary group](#linux-property-group)) the ``` <> -The [shell](https://en.wikipedia.org/wiki/Shell_(computing)) the user should have. If not defined means this requirement won'T be evaluated or applied (in case of creation/modification of a user). +The [shell](https://en.wikipedia.org/wiki/Shell_(computing)) the user should have. Not defined means this requirement won'T be evaluated or applied (in case of creation/modification of a user). <> -The home directory the user should have. If not defined means this requirement won't be evaluated or applied (in case of creation/modification of a user). +The home directory the user should have. Not defined means this requirement won't be evaluated or applied (in case of creation/modification of a user). <> -Is a directory on the Bifröst hosts where a user that needs to be created, will receive its initial files of its [home directory](#linux-property-homeDir) from (= user's home skeleton/template directory). +If a new user needs to be created in a directory on the Bifröst hosts, it will receive its initial files of its [home directory](#linux-property-homeDir) from (= user's home skeleton/template directory). <> Will create the local user if it does not exist to match the provided requirements (see below). If this property is `false` the user has to exist, otherwise the execution will fail and the connection will be closed immediately. @@ -251,7 +251,7 @@ In combination with [`deleteManagedUser`](#linux-dispose-property-deleteManagedU The Windows variant is only supported by Windows 7+ based operating systems. -!!! warning +!!! Warning In contrast to the [Linux](#linux) version this variant **CANNOT** [impersonate](https://en.wiktionary.org/wiki/impersonate). As a consequence, each user session always executes as the user the Bifröst process itself runs with. Impersonating on a Windows machine requires either full credentials (password) or another running process the session tokens can be cloned from. As both conflicts how we intend Bifröst to work, both solutions leave a lot of use-cases behind. Since it is very "hacky", we decided to stick with the simple approach. diff --git a/docs/reference/session/fs.md b/docs/reference/session/fs.md index f3b9e51..a386d86 100644 --- a/docs/reference/session/fs.md +++ b/docs/reference/session/fs.md @@ -4,7 +4,7 @@ description: How to store Bifröst sessions on the local filesystem. # Filesystem session -This variant of [session](index.md) is stored on the same local filesystem where also Bifröst is running. +This variant of [session](index.md) is stored on the same local filesystem onb which also Bifröst is running. ## Properties