sevenhill/QSfera
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Apply suggestions from proof reading

Browse Source 
Co-authored-by: Martin <github@diemattels.at>
This commit is contained in:
Ralf Haferkamp
2024-07-08 09:32:23 +02:00
committed by Ralf Haferkamp
co-authored by Martin
parent bda35131bd
commit 60741472ac
1 changed files with 40 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
services/proxy/README.md
+40 -40
View File
@@ -52,22 +52,21 @@ unprotected: false # with false (default), calling the endpoint requires authori
## Automatic User and Group Provisioning ## Automatic User and Group Provisioning
When using and external OpenID Connect IDP the proxy can be configured to automatically provision When using an external OpenID Connect IDP, the proxy can be configured to automatically provision
users upon their first login. users upon their first login.
### Prequisites ### Prequisites
A number of prerequisites must be met for automatic user provisioning to work: A number of prerequisites must be met for automatic user provisioning to work:
* ownCloud Infinite Scale must be configured to use an external OpenID Connect * ownCloud Infinite Scale must be configured to use an external OpenID Connect IDP
IDP
* The `graph` service must be configured to allow updating users and groups * The `graph` service must be configured to allow updating users and groups
(`GRAPH_LDAP_SERVER_WRITE_ENABLED`) (`GRAPH_LDAP_SERVER_WRITE_ENABLED`).
* The IDP must return a unique value in the user's claims (as part of the * The IDP must return a unique value in the user's claims (as part of the
userinfo response and/or the access tokens) that can be used to identify userinfo response and/or the access tokens) that can be used to identify
the user. This claim needs to be stable and cannot be changed for the whole the user. This claim needs to be stable and cannot be changed for the whole
lifetime of the user. That means if a claim like `email` or lifetime of the user. That means, if a claim like `email` or
`preferred_username` is used, you must asure that the user's email address or `preferred_username` is used, you must ensure that the user's email address or
username never changes. username never changes.
### Configuration ### Configuration
@@ -75,35 +74,37 @@ A number of prerequisites must be met for automatic user provisioning to work:
To enable automatic user provisioning, the following environment variables must To enable automatic user provisioning, the following environment variables must
be set for the proxy service: be set for the proxy service:
* `PROXY_AUTOPROVISION_ACCOUNTS`: Set to `true` to enable automatic user provisioning. * `PROXY_AUTOPROVISION_ACCOUNTS`\
* `PROXY_AUTOPROVISION_CLAIM_USERNAME`: The name of an OIDC claim whose value Set to `true` to enable automatic user provisioning.
should be used as the username for the autoprovsioned user in ownCloud * `PROXY_AUTOPROVISION_CLAIM_USERNAME`\
Infinite Scale. Defaults to `preferred_username`. Can also be set to e.g. The name of an OIDC claim whose value should be used as the username for the
`sub` to guarantee a unique and stable username. autoprovsioned user in ownCloud Infinite Scale. Defaults to `preferred_username`.
* `PROXY_AUTOPROVISION_CLAIM_EMAIL`: The name of an OIDC claim whose value Can also be set to e.g. `sub` to guarantee a unique and stable username.
should be used for the `mail` attribute of the autoprovisioned user in * `PROXY_AUTOPROVISION_CLAIM_EMAIL`\
ownCloud Infinite Scale. Defaults to `email`. The name of an OIDC claim whose value should be used for the `mail` attribute
* `PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME`: The name of an OIDC claim whose of the autoprovisioned user in ownCloud Infinite Scale. Defaults to `email`.
value should be used for the `displayname` attribute of the autoprovisioned * `PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME`\
user in ownCloud Infinite Scale. Defaults to `name`. The name of an OIDC claim whose value should be used for the `displayname`
* `PROXY_AUTOPROVISION_CLAIM_GROUPS`: The name of an OIDC claim whose value attribute of the autoprovisioned user in ownCloud Infinite Scale. Defaults to `name`.
should be used to maintain a user's group membership. The claim value should * `PROXY_AUTOPROVISION_CLAIM_GROUPS`\
contain a list of group names the user should be a member of. Defaults to The name of an OIDC claim whose value should be used to maintain a user's group
`groups`. membership. The claim value should contain a list of group names the user should
* `PROXY_USER_OIDC_CLAIM`: When resolving and authenticated OIDC user, the be a member of. Defaults to `groups`.
value of this claims is used to lookup the user in the users service. For * `PROXY_USER_OIDC_CLAIM`\
auto provisioning setups this usually is the same claims as set via When resolving and authenticated OIDC user, the value of this claims is used to
`PROXY_AUTOPROVISION_CLAIM_USERNAME`. lookup the user in the users service. For auto provisioning setups this usually is the
* `PROXY_USER_CS3_CLAIM`: This is the name of the user attribute in ocis that same claims as set via `PROXY_AUTOPROVISION_CLAIM_USERNAME`.
is used to lookup the user by the value of the `PROXY_USER_OIDC_CLAIM`. For * `PROXY_USER_CS3_CLAIM`\
auto provisioning setups this usually needs to be set to `username`. This is the name of the user attribute in ocis that is used to lookup the user by the
value of the `PROXY_USER_OIDC_CLAIM`. For auto provisioning setups this usually
needs to be set to `username`.
### How it works ### How it Works
When a user logs into ownCloud Infinite Scale for the first time, the proxy When a user logs into ownCloud Infinite Scale for the first time, the proxy
checks if that user already exists by querying the `users` service for users checks if that user already exists. This is done by querying the `users` service for users,
where the attribute set in `PROXY_USER_CS3_CLAIM` matches the value of the OIDC where the attribute set in `PROXY_USER_CS3_CLAIM` matches the value of the OIDC
claim configure in `PROXY_USER_OIDC_CLAIM`. claim configured in `PROXY_USER_OIDC_CLAIM`.
If the users does not exist, the proxy will create a new user via the `graph` If the users does not exist, the proxy will create a new user via the `graph`
service using the claim values configured in service using the claim values configured in
@@ -111,16 +112,16 @@ service using the claim values configured in
`PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME`. `PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME`.
If the user does already exist, the proxy will check if the user's email or If the user does already exist, the proxy will check if the user's email or
displayname has changed and update those accordingly via `graph` service. displayname has changed and updates those accordingly via `graph` service.
Next, the proxy will check if the user is a member of the groups configured in Next, the proxy will check if the user is a member of the groups configured in
`PROXY_AUTOPROVISION_CLAIM_GROUPS`. It will add the user to the groups listed `PROXY_AUTOPROVISION_CLAIM_GROUPS`. It will add the user to the groups listed
in there and remove it from all other groups that it is currently a member of. via the OIDC claim that holds the groups defined in the envvar and removes it from
Groups that do not exist yet will be created. Note: This can be a somewhat all other groups that he is currently a member of.
costly operation, especially if the user is a member of a large number of Groups that do not exist in the external IDP yet will be created. Note: This can be a
somewhat costly operation, especially if the user is a member of a large number of
groups. If the group memberships of a user are changed in the IDP after the groups. If the group memberships of a user are changed in the IDP after the
first login it can take up to 5 minutes until the changes are reflected in first login, it can take up to 5 minutes until the changes are reflected in Infinite Scale.
ownCloud Infinite Scale.
## Automatic Quota Assignments ## Automatic Quota Assignments
@@ -149,9 +150,8 @@ is unset.
When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` the role assignment for a user will happen When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` the role assignment for a user will happen
based on the values of an OpenID Connect Claim of that user. The name of the OpenID Connect Claim to based on the values of an OpenID Connect Claim of that user. The name of the OpenID Connect Claim to
be used for the role assignment can be configured via the `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM` be used for the role assignment can be configured via the `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`
environment variable. It is also possible to defe ine a mapping of claim values to role names defined environment variable. It is also possible to define a mapping of claim values to role names defined
in ownCloud Infinite Scale via a `yaml` configuration. See the following `proxy.yaml` snippet for an in Infinite Scale via a `yaml` configuration. See the following `proxy.yaml` snippet for an example.
example.
```yaml ```yaml
role_assignment: role_assignment: