Add description of client registration variables/properties (#122)

content/en/docs/reference/configuration/_index.md

@@ -388,6 +388,34 @@ IAM_NOTIFICATION_CLEANUP_AGE=30
 IAM_ACCOUNT_LINKING_DISABLE=false 
 ```
 
+## Client registration
+
+Those variables allow to configure how to register a new client and
+the related default settings.
+
+For more information see the [Client registration
+section]({{< ref "/docs/reference/configuration/client-registration" >}}).
+
+```bash
+# Specifies who can register a client. Default is anyone, so also not registered users.
+# Other possible values are: REGISTERED_USERS and ADMINISTRATORS
+IAM_CLIENT_REGISTRATION_ALLOW_FOR=ANYONE
+# Set to false if you do not want to enable client registration (default is true)
+IAM_CLIENT_REGISTRATION_ENABLE=true
+# Set the default validity in seconds of an AT requested by any newly registered client.
+# Default is 1 hour, but it can be changed per client
+IAM_DEFAULT_ACCESS_TOKEN_VALIDITY_SECONDS=3600
+# Set the default validity in seconds of a device code requested by any newly registered client.
+# Default is 10 minutes, but it can be changed per client
+IAM_DEFAULT_DEVICE_CODE_VALIDITY_SECONDS=600
+# Set the default validity in seconds of an ID token requested by any newly registered client.
+# Default is 10 minutes, but it can be changed per client
+IAM_DEFAULT_ID_TOKEN_VALIDITY_SECONDS=600
+# Set the default validity in seconds of an RT requested by any newly registered client.
+# Default is 30 days, but it can be changed per client
+IAM_DEFAULT_REFRESH_TOKEN_VALIDITY_SECONDS=2592000
+```
+
 ## Client lifecycle
 
 ```bash

content/en/docs/reference/configuration/client-registration/_index.md

@@ -0,0 +1,68 @@
+---
+title: "Client registration"
+linkTitle: "Client registration"
+weight: 7
+---
+
+IAM has the ability to enable or disable the client registration, and
+to limit the registration to certain users.
+The default behavior is that anyone can register a client, even
+anonymous users.
+
+To have control over the below properties using the environment
+variables, please check the [Configuration][conf] section.
+
+### Disable client registration
+
+In order to totally disable the client registration, set
+
+```yaml
+iam:
+  client-registration:
+    enable: false 
+```
+
+The client registration is enabled by default in IAM.
+
+
+### Specify who can register a client
+
+In order to specify who can register a client, please set one
+among _ANYONE_, _REGISTERED_USERS_ or _ADMINISTRATORS_ such
+to limit to all, IAM users or administrators only the
+client registration
+
+```yaml
+iam:
+  client-registration:
+    allow-for: <ANYONE|REGISTERED_USERS|ADMINISTRATORS> 
+```
+
+The client registration is enabled for anyone by default.
+
+
+### Default settings of a new client
+
+For any newly registered client, the default value of the related
+access token, device code, ID token and refresh token lifetimes
+can be set trough the following properties
+
+```yaml
+iam:
+  client-registration:
+    client-defaults:
+      # IAM default is 1 hour
+      default-access-token-validity-seconds: 3600
+      # IAM default is 10 minutes
+      default-device-code-validity-seconds: 600
+      # IAM default is 10 minutes
+      default-id-token-validity-seconds: 600
+      # IAM default is 30 days
+      default-refresh-token-validity-seconds: 2592000
+```
+
+The above values can be changed per client trough web interface
+or API by an IAM administrator.
+
+
+[conf]: ../#client-registration

content/en/docs/reference/configuration/registration/_index.md

@@ -24,7 +24,6 @@ a volume providing this file must be mapped into the container.
 The contents in this file must be under the following hierarchy:
 
 ```yaml
-
 iam:
   registration:
 ```
@@ -42,7 +41,6 @@ It also defines how information from identity tokens issued by CERN SSO is
 mapped to IAM membership information
 
 ```yaml
-
 iam:
   registration:
     require-external-authentication: true
@@ -86,6 +84,29 @@ when it is required.**
 `external-auth-attribue` must be the name of the IdP attribute, or token claim (when provided by SAML IdPs,
 or OIDC Providers, respectively) to use for the mentioned account creation form field.
 
+
+## Automatic enrollment through SAML IdPs
+
+In case of registration through an external SAML Identity Provider, IAM offers
+a flexible user enrollment flow, also without IAM admin intervention. The default IAM
+behavior is that the user enrollment requires an administrator approval step.
+
+In order to enable the automatic enrollment flow via an external IdP, one
+should set the following properties, under the `saml` hierarchy:
+
+```yaml
+saml:
+  jit-account-provisioning:
+    enabled: true
+    # this will consider as trusted all the IdPs declared in your
+    # application-saml.yml file
+    trusted-idps: all
+```
+
+In order to directly declare the list of trusted SAML IdPs, a comma separated list of
+entity IDs have to be set, e.g. `saml.jit-account-provisioning.trusted-idps=idp1,idp2,idp3`.
+
+
 ## User editable fields
 
 Starting with version 1.6.0, IAM allows to limit which fields of the user profile are editable by users.
@@ -94,7 +115,6 @@ The default, backward-compatible settings that allow users to edit all their
 profile fields are defined as follows:
 
 ```yaml
-
 iam:
   user-profile:
     editable-fields:
@@ -111,25 +131,26 @@ External configuration can be managed by placing directives as shown above in a
 [custom configuration
 file][custom-config-file]
 
-## Automatic enrollment trough SAML IdPs
 
-In case of registration trough an external SAML Identity Provider, IAM offers
-a flexible user enrollment flow, also without IAM admin intervention. The default IAM
-behavior is that the user enrollment requires an administrator approval step.
+## Automatically set the nickname as attribute
 
-In order to enable an automatic enrollment flow trough an external IdP, one
-should set the following properties, under the `saml` hierarchy:
+Since IAM v1.9.0, during a registration request the username can be automatically added as an attribute named _nickname_. This process happens both for login with external provider, or when one directly clicks on the
+_Apply for an account_ button.
+The _nickname_ value will be the same as the username set during the registration request.
+
+This behavior does not appear by default. To enable it, add to your config file
 
 ```yaml
-saml:
-  jit-account-provisioning:
-    enabled: true
-    # this will consider as trusted all the IdPs declared in your
-    # application-saml.yml file
-    trusted-idps: all
+iam:
+  registration:
+    add-nickname-as-attribute: true
 ```
 
-In order to directly declare the list of trusted SAML IdPs, a comma separated list of
-entity IDs have to be set, e.g. `saml.jit-account-provisioning.trusted-idps=idp1,idp2,idp3`.
+or set the environment variable `IAM_ADD_NICKNAME_AS_ATTRIBUTE=true`.
+
+Once the new IAM user has been created, the _Attributes_ view from the dashboard looks like the following
+
+![Attributes view](./nickname-attribute.png)
+
 
 [custom-config-file]: {{< ref "/docs/reference/configuration/#overriding-default-configuration-templates" >}}

content/en/docs/reference/configuration/scim-response/_index.md

@@ -0,0 +1,146 @@
+---
+title: "Handling SCIM response"
+linkTitle: "SCIM response"
+weight: 6
+---
+
+IAM already supports a set of [SCIM APIs](../../api/scim-api/_index.md) based on the System for Cross-domain
+Identity Management standard. Starting from IAM v1.9.0, the API response to GET requests on user details
+(i.e. `/scim/Me` and `/scim/Users`) are extended with more information.
+All the new details are included into the _IndigoUser_ field.
+To enable this feature, dedicated properties (or environment variables) must be used to maintain backward compatibility.
+
+The list of information that may be included into the SCIM response are:
+
+* user's autorities
+* set of user-managed groups
+* set of user's attributes.
+
+
+### Authorities
+
+In order to include the list of user's authorities (i.e. `ROLE_USER`, `ROLE_ADMIN`, `ROLE_GM:<group-uid>`, etc.) into the SCIM response,
+one should set the following property (default is false):
+
+```yaml
+scim:
+  include_authorities: true
+```
+
+or the environment variable `IAM_SCIM_INCLUDE_AUTHORITIES=true`.
+
+Then, an example of SCIM Me output for an administrator user is the following:
+
+```
+{
+  "id": "73f16d93-2441-4a50-88ff-85360d78c6b5",
+  "meta": {  ...  },
+  "schemas": [
+      "urn:ietf:params:scim:schemas:core:2.0:User",
+      "urn:indigo-dc:scim:schemas:IndigoUser"
+  ],
+  ...
+  "userName": "admin",
+  ...
+  "active": true,
+  "urn:indigo-dc:scim:schemas:IndigoUser": {
+    "oidcIds": [ ... ],
+    "samlIds": [ ... ],
+    "certificates": [ ... ],
+    "authorities": [
+      "ROLE_ADMIN",
+      "ROLE_USER"
+    ]
+  }
+}
+```
+
+
+### Managed groups
+
+In order to include the list of user-managed groups into the SCIM response,
+one should set the following property (default is false):
+
+```yaml
+scim:
+  include_managed_groups: true
+```
+
+or the environment variable `IAM_SCIM_INCLUDE_MANAGED_GROUPS=true`.
+
+Then, an example of SCIM Me output for a group manager is the following:
+
+```
+{
+  "id":"80e5fb8d-b7c8-451a-89ba-346ae278a66f",
+  "meta":{ ... },
+  "schemas":[
+     "urn:ietf:params:scim:schemas:core:2.0:User",
+     "urn:indigo-dc:scim:schemas:IndigoUser"
+  ],
+  ...
+  "userName": "gm-user",
+  ...
+  "active": "true",
+  "urn":"indigo-dc:scim:schemas:IndigoUser":{
+     "oidcIds":[ ... ]
+     "samlIds":[ ... ],
+     "endTime": "2024-08-06T02:00:00.000+02:00",
+     "managedGroups":[
+        {
+           "display":"Analysis",
+           "value":"6a384bcd-d4b3-4b7f-a2fe-7d897ada0dd1",
+           "$ref":"http://localhost:8080/scim/Groups/6a384bcd-d4b3-4b7f-a2fe-7d897ada0dd1"
+        },
+        {
+           "display":"Production",
+           "value":"c617d586-54e6-411d-8e38-64967798fa8a",
+           "$ref":"http://localhost:8080/scim/Groups/c617d586-54e6-411d-8e38-64967798fa8a"
+        }
+     ]
+  }
+}
+```
+
+### Attributes
+
+In order to include the list of user's attributes, selected by attribute name, into the SCIM response,
+one should set the following property (default is false):
+
+```yaml
+scim:
+  include_attributes:
+  - name: nickname
+  - name: another-attribute-name
+```
+
+Then, an example of SCIM Me output for an IAM user is the following:
+
+```
+{
+  "id":"d836e5ec-246c-456c-8476-923ee2f831c8",
+  "meta":{ ... },
+  "schemas":[
+     "urn:ietf:params:scim:schemas:core:2.0:User",
+     "urn:indigo-dc:scim:schemas:IndigoUser"
+  ],
+  ...
+  "userName": "tester",
+  ...
+  "active": "true",
+  "urn":"indigo-dc:scim:schemas:IndigoUser":{
+    "oidcIds":[ ... ]
+    "samlIds":[ ... ],
+    "endTime": "2024-08-06T02:00:00.000+02:00",
+    "attributes":[
+       {
+          "name":"nickname",
+          "value":"tester"
+       }
+    ],
+    "endTime": "2024-08-06T02:00:00.000+02:00"
+  }
+}
+```
+
+In this example the user has only one attribute, named _nickname_, so the second attribute (_another-attribute-name_) is not shown into the SCIM response.