arcanis/ahriman
1
0
Fork 0
mirror of https://github.com/arcan1s/ahriman.git synced 2025-04-24 15:27:17 +00:00
Code Issues Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Evgenii Alekseev 2021-09-12 21:25:45 +03:00
parent 9e782bb0b1
commit d12eaba034
6 changed files with 42 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/architecture.md
View File

@ -107,6 +107,32 @@ For every external command run (which is actually not recommended if possible) c
Some packages provide different behaviour depending on configuration settings. In this cases inheritance is used and recommended way to deal with them is to call class method `load` from base classes.
## Authorization
The package provides several authorization methods: disabled, based on configuration and OAuth2.
Disabled (default) authorization provider just allows everything for everyone and does not have any specific configuration (it uses some default configuration parameters though). It also provides generic interface for derived classes.
Mapping (aka configuration) provider uses hashed passwords with salt from configuration file in order to authenticate users. This provider also enables user permission checking (read/write) (authorization). Thus, it defines the following methods:
* `check_credentials` - user password validation (authentication).
* `verify_access` - user permission validation (authorization).
Passwords must be stored in configuration as `hash(password + salt)`, where `password` is user defined password (taken from user input), `salt` is random string (any length) defined globally in configuration and `hash` is secure hash function. Thus, the following configuration
```ini
[auth:read]
username = $6$rounds=656000$mWBiecMPrHAL1VgX$oU4Y5HH8HzlvMaxwkNEJjK13ozElyU1wAHBoO/WW5dAaE4YEfnB0X3FxbynKMl4FBdC3Ovap0jINz4LPkNADg0
```
means that there is user `username` with `read` access and password `password` hashed by `sha512` with salt `salt`.
OAuth provider uses library definitions (`aioauth-client`) in order _authenticate_ users. It still requires user permission to be set in configuration, thus it inherits mapping provider without any changes. Whereas we could override `check_credentials` (authentication method) by something custom, OAuth flow is a bit more complex than just forward request, thus we have to implement the flow in login form.
OAuth's implementation also allows authenticating users via username + password (in the same way as mapping does) though it is not recommended for end-users and password must be left blank. In particular this feature is used by service reporting (aka robots).
In order to configure users there is special command.
## Additional features
Some features require optional dependencies to be installed:
@ -122,7 +148,8 @@ Some features require optional dependencies to be installed:
Web application requires the following python packages to be installed:
* Core part requires `aiohttp` (application itself), `aiohttp_jinja2` and `Jinja2` (HTML generation from templates).
* In addition authorization feature requires `aiohttp_security`, `aiohttp_session` and `cryptography`.
* In addition, authorization feature requires `aiohttp_security`, `aiohttp_session` and `cryptography`.
* In addition to base authorization dependencies, OAuth2 also requires `aioauth-client` library.
## Middlewares
@ -150,7 +177,7 @@ Service provides optional authorization which can be turned on in settings. In o
If this feature is configured any request except for whitelisted will be prohibited without authentication. In addition, configuration flag `auth.allow_read_only` can be used in order to allow seeing main page without authorization (this page is in default white list).
For authorized users it uses encrypted session cookies to store tokens; encryption key is generated each time at the start of the application.
For authenticated users it uses encrypted session cookies to store tokens; encryption key is generated each time at the start of the application.
## External calls

10
docs/configuration.md
View File

@ -20,17 +20,17 @@ libalpm and AUR related configuration.
## `auth` group
Base authorization settings. `OAuth2` provider requires `aioauth-client` library to be installed.
Base authorization settings. `OAuth` provider requires `aioauth-client` library to be installed.
* `target` - specifies authorization provider, string, optional, default `disabled`. Allowed values are `disabled`, `configuration`, `oauth`.
* `allow_read_only` - allow requesting read only pages without authorization, boolean, required.
* `allowed_paths` - URI paths (exact match) which can be accessed without authorization, space separated list of strings, optional.
* `allowed_paths_groups` - URI paths prefixes which can be accessed without authorization, space separated list of strings, optional.
* `client_id` - OAuth2 application client ID, string, required in case if `oauth2` is used.
* `client_secret` - OAuth2 application client secret key, string, required in case if `oauth2` is used.
* `client_id` - OAuth2 application client ID, string, required in case if `oauth` is used.
* `client_secret` - OAuth2 application client secret key, string, required in case if `oauth` is used.
* `max_age` - parameter which controls both cookie expiration and token expiration inside the service, integer, optional, default is 7 days.
* `oauth_provider` - OAuth2 provider class name as is in `aioauth-client` (e.g. `GoogleClient`, `GithubClient` etc), string, required in case if `oauth2` is used.
* `oauth_scopes` - scopes list for OAuth2 provider, which will allow retrieving user email (which is used for checking user permissions), e.g. `https://www.googleapis.com/auth/userinfo.email` for `GoogleClient` or `user:email` for `GithubClient`, space separated list of strings, required in case if `oauth2` is used.
* `oauth_provider` - OAuth2 provider class name as is in `aioauth-client` (e.g. `GoogleClient`, `GithubClient` etc), string, required in case if `oauth` is used.
* `oauth_scopes` - scopes list for OAuth2 provider, which will allow retrieving user email (which is used for checking user permissions), e.g. `https://www.googleapis.com/auth/userinfo.email` for `GoogleClient` or `user:email` for `GithubClient`, space separated list of strings, required in case if `oauth` is used.
* `salt` - password hash salt, string, required in case if authorization enabled (automatically generated by `create-user` subcommand).
## `auth:*` groups

6
package/share/ahriman/build-status.jinja2
View File

@ -14,7 +14,7 @@
<div class="container">
<h1>ahriman
{% if auth.authorized %}
{% if auth.authenticated %}
<img src="https://img.shields.io/badge/version-{{ version }}-informational" alt="{{ version }}">
<img src="https://img.shields.io/badge/repository-{{ repository }}-informational" alt="{{ repository }}">
<img src="https://img.shields.io/badge/architecture-{{ architecture }}-informational" alt="{{ architecture }}">
@ -70,7 +70,7 @@
</thead>
<tbody>
{% if auth.authorized %}
{% if auth.authenticated %}
{% for package in packages %}
<tr data-package-base="{{ package.base }}">
<td data-checkbox="true"></td>
@ -85,7 +85,7 @@
{% endfor %}
{% else %}
<tr>
<td colspan="100%">In order to see statuses you must login first</td>
<td colspan="100%">In order to see statuses you must login first.</td>
</tr>
{% endif %}
</tbody>

2
src/ahriman/core/auth/auth.py
View File

@ -63,7 +63,7 @@ class Auth:
def auth_control(self) -> str:
"""
This workaround is required to make different behaviour for login interface.
In case of internal authorization it must provide an interface (modal form) to login with button sends POST
In case of internal authentication it must provide an interface (modal form) to login with button sends POST
request. But for an external providers behaviour can be different: e.g. OAuth provider requires sending GET
request to external resource
:return: login control as html code to insert

2
src/ahriman/web/middlewares/auth_handler.py
View File

@ -48,7 +48,7 @@ class AuthorizationPolicy(aiohttp_security.AbstractAuthorizationPolicy): # type
async def authorized_userid(self, identity: str) -> Optional[str]:
"""
retrieve authorized username
retrieve authenticated username
:param identity: username
:return: user identity (username) in case if user exists and None otherwise
"""

6
src/ahriman/web/views/index.py
View File

@ -35,10 +35,10 @@ class IndexView(BaseView):
architecture - repository architecture, string, required
auth - authorization descriptor, required
* authorized - alias to check if user can see the page, boolean, required
* authenticated - alias to check if user can see the page, boolean, required
* control - HTML to insert for login control, HTML string, required
* enabled - whether authorization is enabled by configuration or not, boolean, required
* username - authorized username if any, string, null means not authorized
* username - authenticated username if any, string, null means not authenticated
packages - sorted list of packages properties, required
* base, string
* depends, sorted list of strings
@ -88,7 +88,7 @@ class IndexView(BaseView):
# auth block
auth_username = await authorized_userid(self.request)
auth = {
"authorized": not self.validator.enabled or self.validator.allow_read_only or auth_username is not None,
"authenticated": not self.validator.enabled or self.validator.allow_read_only or auth_username is not None,
"control": self.validator.auth_control,
"enabled": self.validator.enabled,
"username": auth_username,