Skip to content

Commit

Permalink
Merge branch 'master' into feature/attribute-caching
Browse files Browse the repository at this point in the history
  • Loading branch information
@mederly
mederly committed Nov 14, 2023
2 parents 47fe059 + d876159 commit e0642a2
Show file tree
Hide file tree
Showing 111 changed files with 3,655 additions and 2,637 deletions.
22 changes: 12 additions & 10 deletions docs/deployment/ninja/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,10 @@ Connection options:
=== midpoint.home connection

This type of connection initialises repository layer of midPoint and operates on top of the database as a new midPoint node.
Mostly only one option is needed and that's specification of `midpoint.home` directory using `-m` option.
This is not sufficient if `config.xml` uses datasource definition.
Ninja then doesn't know how to connect to DB.
For this case one have to use options to specify URL (`-U`), username (`-u`) and password (`-p` or `-P`).
For all commands that communicate with DB layer `midpoint.home` must be specified using `-m <path>` option.
Ninja will try to read database connection information from `config.xml`.
This will not work when there's only datasource definition in `config.xml` (no JDBC url/username/password).
In such chase one have to specify URL (`-U`), username (`-u`) and password (`-p` or `-P`).
These options can also be used to override JDBC URL, username and password specified in `config.xml`.

With bash, you can provide `MIDPOINT_HOME` for the `ninja.sh` command with this shortcut:
Expand All @@ -62,24 +62,26 @@ With bash, you can provide `MIDPOINT_HOME` for the `ninja.sh` command with this
MIDPOINT_HOME=/var/other-mp-home <midpoint>/bin/ninja.sh [general options] [command] [command options]
----

If unbundled JDBC driver is used, it will not be picked up automatically from the midPoint home directory
and you must point Ninja to it explicitly.
=== JDBC Driver

Only JDBC driver that is bundled is for PostgreSQL database.
This means that for other databases, you must provide JDBC driver yourself.
Most of the time JDBC driver is already present in `<midpoint>/lib` directory.
However, it will not be picked up automatically and you must point Ninja to it explicitly.
Example when using `java -jar`:

[source,bash]
----
java -Dloader.path=<jdbc_driver_jar_path> -jar ninja.jar [general options] [command] [command options]
java -Dloader.path=<jdbc_driver_jar_path> -jar ninja.jar [general/connection options] [command] [command options]
----

If the bundled scripts are used, you can specify the path to the driver with `-j` option, for example:

[source,bash]
----
<midpoint>/bin/ninja.sh -j <JDBC_DRIVER_JAR> [general options] [command] [command options]
<midpoint>/bin/ninja.sh -j <jdbc_driver_jar_path> [general/connection options] [command] [command options]
----

// TODO: mention python CLI

== Supported operations

Ninja currently supports these operations:
Expand Down
133 changes: 72 additions & 61 deletions docs/misc/self-registration/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,28 @@
:page-toc: top
:page-since: "4.6"
:page-upkeep-status: yellow
:page-toc: top

Self registration in midPoint provides possibility for unauthenticated user to enroll to midPoint and request assignments.

Also this feature covers the post-registration scenario when a user already exists in the system (e.g. a user was created by administrator) and self registration process starts after the user opens the invitation link sent to them by the system.
This scenario is called _Invitation_ flow.

By default, self registration is disabled.
Following text describes how to enable self registration in midPoint.

Following text describes how to enable and configure self registration in midPoint.

== Enabling Self Registration

To enable this feature you'll need to configure security policy and reference this security policy from system configuration.
To enable this feature it's necessary to configure security policy and reference this security policy from the system configuration.
After this, self registration process is enabled globally (in the multi-tenant environment it means that the configuration will be shared between tenants, the plan is to support self registration configuration per tenant in later midPoint versions).


[source,xml]
----
<systemConfiguration xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"
xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
xmlns:icfs="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-3"
xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
...
oid="00000000-0000-0000-0000-000000000001">
<name>SystemConfiguration</name>
....
Expand All @@ -43,21 +46,18 @@ This value is used while generating confirmation link for self registration veri

== Configuring Security Policy

Configuration for self registration is in Security Policy object and it is separated into three parts - registration, authentication and credentials.
Configuration for self registration is situated in Security Policy object and it is separated into three parts - registration, authentication and credentials.
Using these three parts you can configure the self registration process, e.g how to confirm registered user, which roles should be assigned to the user after confirmation and more.
Basically there are two major different scenarios:

* self-registration for the new users

* self post-registration (or invitation) for existing users in midPoint

More about security policy configuration and merging different security policies can be found xref:/midpoint/reference/security/security-policy/[here].

== Self Registration For The New Users

In this scenario, users are allowed to register by themselves.
There is no policy and rules which force the existence of the user in the midPoint or anything like this.
In this scenario, users are allowed to register themselves.
There is no policy and rules which check the existence of the user in the midPoint or anything like this.
Self registration allows everyone to register to the midPoint.
The configuration for self registration can look like following:
The configuration for self registration can look like the following:

[source,xml]
----
Expand All @@ -74,7 +74,7 @@ The configuration for self registration can look like following:

With the configuration above, after user submits the registration form, a new user entry is created in midPoint.
For this newly created user, lifecycle state is set to the draft.
Until user doesn't confirm his/her registration it cannot do anything, it is disabled and no roles are assigned.
Until user doesn't confirm their registration they cannot do anything, they are disabled and no roles are assigned.
After confirmation, specified default roles are assigned to the user.

== Self Post-Registration (or Invitation) For Existing Users in MidPoint
Expand All @@ -94,9 +94,8 @@ After the year, they are marked as disabled and are requested to remake the regi

* You started to provide new service and you want to invite some users to use this service.

* .....

To activate the invitation flow the same flow configuration should be used.
To activate the invitation flow the similar flow configuration should be used.

[source,xml]
----
Expand All @@ -112,34 +111,39 @@ To activate the invitation flow the same flow configuration should be used.
</flow>
----

The invitation flow also requires an invitation sequence to be added to the authentication part of the security policy (please, see Authentication Part chapter) and a notifier to be configured to send the invitation link to be configured (please, see Email Notifications chapter). For invitation sequence a mail nonce authentication module is used. As for notifier, different possibilities are available depending on the use case, in this documentation simple user notifier configuration is used to generate and send an invitation link.
The invitation flow also requires an invitation sequence to be added to the authentication part of the security policy (please, see Authentication Part chapter) and a notifier to be configured to send the invitation link (please, see Email Notifications chapter).
For invitation sequence a mail nonce authentication module is used.
As for notifier, different possibilities are available depending on the use case, in this documentation simple user notifier configuration is used to generate and send an invitation link.
Current flow requires that the user already exists in midPoint.
The lifecycle state which is required to successfully register the user is specified with attribute requiredLifecyleState.
This is to support situations, where all potential users are pre-created/pre-registered by administrators (but they are not active until they don't register and confirm the registration).
After user fills in registration form and submits it, existing user is modified in midPoint with the configured lifecycle state (initialLifecycleState attribute).
This newly created user is disabled and doesn't have any roles assigned until he/she confirms the registration.
Confirmation of registration is configurable using additionalAuthenticationSequence attribute.
After user successfully confirms the registration, default roles are assigned to him/her - default roles are configured using defaultRole attribute.
After the user successfully confirms the registration, default roles are assigned to them (default roles are configured using defaultRole attribute).

More information about lifecycle configuration, please, see xref:/midpoint/reference/security/authentication/post-authentication-configuration/#configure-lifecycle-activation[Configure lifecycle activation]
For more information about lifecycle configuration, please, see xref:/midpoint/reference/security/authentication/post-authentication-configuration/#configure-lifecycle-activation[Configure lifecycle activation]

As an example let's see on the use case when the user is created by the administrator and the invitation link is sent to the user.

1. Administrator creates new user. Lifecycle state is set to Draft (notification configuration example sends invitation link just in case when the lifecycle is draft).
1. Administrator creates new user.
Lifecycle state is set to Draft (notification configuration example sends invitation link just in case when the lifecycle is draft).

2. Simple user notifier is triggered. Invitation link is created (please, see notification configuration part) and sent to the user. While this action producing the nonce is created and saved to the new user. This nonce is used to authenticate the user while invitation link opening.

3. The user receives the link and opens it.

4. Registration form is opened. The user fills in the necessary fields and confirms the form.
4. Registration form is opened.
The user fills in the necessary fields and confirms the form.

5. Registration confirmation link is sent to the user (please, see user registration notifier configuration).

6. User opens registration confirmation link.

7. Invitation flow is finished.If all authentications were successful, the user lifecycle state is changed to Active.
7. Invitation flow is finished.
If all authentications were successful, the user lifecycle state is changed to Active.

=== Authentication Part
== Authentication Part

[source, xml]
----
Expand Down Expand Up @@ -186,8 +190,10 @@ As an example let's see on the use case when the user is created by the administ
----

Authentication part contains one sequence ("selfRegistrationAuth") for the registration confirmation and one sequence ("invitationAuth") for the user authentication while invitation link opening.
In both sequences mail authentication module is used. This means that the user receives the mail with the confirmation/invitation link.
In both sequences mail authentication module is used.
This means that the user receives the mail with the confirmation/invitation link.
After clicking on the link in the mail midPoint tries to authenticate the user.
If the authentication is successful, the user is redirected to the next step.

=== Credentials Part

Expand All @@ -205,8 +211,7 @@ After clicking on the link in the mail midPoint tries to authenticate the user.
Credentials configuration can contain various rules for different types of credentials.
In the example above there is a configuration for nonce credentials.
It is used for generating and validating nonce by self registration.
Max age is the time how long is the nonce valid and valuePolicyRef is reference to the policy used for generating the nonce - e.g. the length, unique characters etc.

Max age is the time how long the nonce is valid and valuePolicyRef is reference to the policy used for generating the nonce - e.g. the length, unique characters etc.

== Self-Registration And Custom Form

Expand All @@ -218,40 +223,47 @@ All what is needed is to reference to the concrete form in the self-registration
[source,xml]
----
<flow>
<selfRegistration>
<selfRegistration>
...
<formRef oid="6818a918-109a-4b82-876b-f72dec9d561a" type="c:FormType"><!-- Registration form --></formRef>
</selfRegistration>
<formRef oid="6818a918-109a-4b82-876b-f72dec9d561a" type="c:FormType"><!-- Registration form --></formRef>
</selfRegistration>
</flow>
----

== Email Notifications

To enable email confirmation notification shall be configured first.
For the registration there is UserRegistrationNotifier.
Configuration looks as follows:
=== Confirmation notification while new user registration

To force midpoint to send confirmation notification, notification part should be configured in the system configuration.
For the registration event there is UserRegistrationNotifier.

* default registration notifier.Simple registration notifier
To send the default message about user's registration, the default notifier should be configured as the following:

.Default user registration notifier.
[source,xml]
----
<userRegistrationNotifier>
<notificationConfiguration>
<handler>
<userRegistrationNotifier>
<recipientExpression>
<script xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="c:ScriptExpressionEvaluatorType">
<code>
return requestee.getEmailAddress()
</code>
</script>
<script xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="c:ScriptExpressionEvaluatorType">
<code>
return requestee.getEmailAddress()
</code>
</script>
</recipientExpression>
<transport>mail</transport>
<confirmationMethod>link</confirmationMethod>
</userRegistrationNotifier>
</userRegistrationNotifier>
</handler>
...
</notificationConfiguration>
----

* custom registration notifier - while using custom expression for the body, don't forget to add call for `midpoint.createRegistrationConfirmationLink(userType); `which will generate the confirmation link needed to finish the registration.
There is also a possibility to configure custom message by using custom expression for the body.
In this case don't forget to add call for `midpoint.createRegistrationConfirmationLink(userType);` which will generate the confirmation link needed to finish the registration.

.Custom notification message.
[source,xml]
----
<notificationConfiguration>
Expand Down Expand Up @@ -291,7 +303,20 @@ Configuration looks as follows:
<confirmationMethod>link</confirmationMethod>
</userRegistrationNotifier>
</handler>
<!-->BEGIN: Handler in case of user's invitation <-->
...
</notificationConfiguration>
----

To make _Invitation_ scenario working, one more notifier should be configured.
This notifier will send invitation link to the user by call for `midpoint.createInvitationLink(userType);` method.
In the following example Simple user notifier is used to send the invitation link.
This notifier is triggerred by the user creation event in case when the lifecycle state of the created user equals to Draft.

.Simple user notifier for sending an invitation link.
[source,xml]
----
<notificationConfiguration>
<handler>
<simpleUserNotifier>
<expressionFilter>
Expand Down Expand Up @@ -329,20 +354,7 @@ Configuration looks as follows:
<transport>mail</transport>
</simpleUserNotifier>
</handler>
<!-->END: Handler in case of user's invitation<-->
<mail>
<server>
<host>smtp.gmail.com</host>
<port>587</port>
<username>mail@google.com</username>
<password>
<t:clearValue>password</t:clearValue>
</password>
<transportSecurity>starttlsRequired</transportSecurity>
</server>
<defaultFrom>mail@gmail.com</defaultFrom>
<debug>true</debug>
</mail>
....
</notificationConfiguration>
----

Expand All @@ -351,7 +363,6 @@ According to the value for the confirmation method, confirmation link/pin is gen
Other parts of configuration are same as for other notifiers.
Details for notification configuration are described xref:/midpoint/reference/misc/notifications/configuration/[here].


== How it works

image::self-registration.png[]
Expand Down
3 changes: 3 additions & 0 deletions docs/roles-policies/pdrbac/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ Privileges and user assignments do not change by themselves, system administrato
This is no small effort, as there are usually a lot of roles to maintain.
It is no exception that there are more roles than there are users, which somehow spoils the original idea of reducing system administration effort.

image::rbac-overview.png[Static RBAC]

Static RBAC models have numerous drawbacks, including xref:/iam/role-explosion/[role explosion], huge role maintenance and access review effort, tendency for over-provisioning and so on.
It is quite clear that _static_ RBAC methods are not suitable for current access control needs.
However, it does not mean the RBAC _idea_ is wrong, or that the concept is completely useless.
Expand Down Expand Up @@ -52,6 +54,7 @@ Similarly `London Supervisor`, `Paris Supervisor` and `New York Supervisor` are

Both _relation_ and _role parameters_ are efficient method to reduce xref:/iam/role-explosion/[role explosion].

image::pdrbac-midpoint-overview.png[Policy-driven RBAC in midPoint]

== Dynamic Assignments

Expand Down
Binary file added docs/roles-policies/pdrbac/pdrbac-midpoint-overview.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit e0642a2

Please sign in to comment.