... | ... | @@ -434,6 +434,86 @@ There should also be statistics collected per callout to monitor performance acr |
|
|
|
|
|
10. Run the Stork. Enjoy!
|
|
|
|
|
|
### Technical troubles
|
|
|
|
|
|
Golang requires that the core and plugin dependencies will be in precisely identical versions. The easiest method to fill this requirement is to add the core as a plugin's dependency. Unfortunately, the Stork core doesn't exist in the Go package registry and cannot be added in the standard way. There is a possibility to specify the dependency by the relative path by using the `go mod replace` command.
|
|
|
|
|
|
|
|
|
|
|
|
## Authentication hook
|
|
|
|
|
|
We decided the first hook would be an authentication hook to support login through LDAP. In the future, we want to implement more authentication hooks this way.
|
|
|
|
|
|
In general, we can split the authentication methods into two groups. The first contains solutions where the server actively mediates in the authentication process. It means that a user provides the credentials in the form presented by the server, and next, the server forwards these credentials to the authentication point. The authentication point validates the credentials and returns the user profile on success. The solutions in the second group use the delegated flow. The user initiates the authentication by clicking the button on the server page. The server redirects to the authentication point page. The user provides the credentials in the form presented by the authentication point that validates the credentials and redirects the user back to the server. The server receives the authentication token that is validated on the server-side. The token may contain the basic user profile, or the server may use it to obtain the profile from the authentication point.
|
|
|
|
|
|
The LDAP authentication belongs to the first group.
|
|
|
|
|
|
The authentication process in Stork starts on the login page. There should be displayed a list of supported authentication methods generated by the dedicated callout. Stork should also provide a flag to suppress the default authentication. The user needs to choose the preferred authentication method. Another approach is allowing only a single authentication method. If the authentication hook is loaded, it replaces the default authentication; only one authentication hook may be loaded simultaneously. The Stork should present a login form or redirect the user to the authentication point page, depending on the selected solution. The hook will be responsible for validating the form data, fetching the profile, and creating the internal user instance. This instance will be passed to the session manager. The hook should provide the possibility to log out the user too.
|
|
|
In the case of delegated authentication, the callout must generate the redirection link and handle the returned token validation.
|
|
|
|
|
|
### LDAP authentication scenario
|
|
|
|
|
|
It is a single authentication solution.
|
|
|
|
|
|
1. The server loads the hooks, including the authentication one
|
|
|
2. The user opens the login page
|
|
|
3. The UI fetches the authentication method details from the server. It displays the login form or redirection button to the authentication point.
|
|
|
4. The server calls the callout point to fetch the authentication details. If no authentication hooks were loaded, then it returns the default method. For LDAP, the login and password form is requested.
|
|
|
5. The UI presents the login and password form.
|
|
|
6. The user provides the credentials and clicks the submit button.
|
|
|
7. The `CreateSession` endpoint receives the credentials. They are passed to the hook.
|
|
|
8. The hook validates the credentials in the LDAP server. Returns an error if they are invalid.
|
|
|
9. The hook fetches the user profile from the LDAP server. It converts the data to the Stork user structure. It needs to translate the groups from the LDAP standard to the Stork indices.
|
|
|
10. The hook returns the user instance.
|
|
|
11. The server creates a session in the session manager.
|
|
|
12. The server returns the user object to the UI.
|
|
|
13. The session middleware sets the authentication cookie.
|
|
|
14. The browser receives the response, reads the cookie, and remembers it.
|
|
|
15. The UI receives the user object, saves it, and redirects to the dashboard.
|
|
|
16. The user uses Stork.
|
|
|
17. The user clicks the logout button.
|
|
|
18. The `DeleteSession` endpoint receives the request and destroys the session. It calls the logout callout point.
|
|
|
19. The UI displays the login page.
|
|
|
|
|
|
### Callout points
|
|
|
|
|
|
1. `GetAuthenticationDetails() Details`
|
|
|
|
|
|
The output structure will contain the control data for the login page:
|
|
|
|
|
|
- Authentication method name
|
|
|
- Authentication method description
|
|
|
- Authentication method icon
|
|
|
- The layout of credentials form:
|
|
|
- Username field name (username, email, identity number, etc.)
|
|
|
- Password type (standard, masked password, passwordless)
|
|
|
- Two-factor authentication field (SMS, authentication code)
|
|
|
- Captcha
|
|
|
- Remember password link
|
|
|
- Or redirect the button to the authentication point
|
|
|
|
|
|
This callout point will call only the first hook. If no hooks are registered, the core will fall back to the standard authentication.
|
|
|
|
|
|
2. `Authenticate(params users.CreateSessionParams) (*SystemUser, error)`
|
|
|
|
|
|
The authenticate callout point will be responsible for validating the credentials and preparing the user instance. It should send the data to the LDAP server. If they are correct, then the hook should fetch the user profile. It must translate the LDAP roles to the Stork groups.
|
|
|
|
|
|
This callout point will be called in the `CreateSession` REST handler. Only the callout from the first hook will be used.
|
|
|
|
|
|
3. `Deauthenticate(*SystemUser) error`
|
|
|
|
|
|
This callout point should close the user sessions in the external authentication point if necessary.
|
|
|
|
|
|
### Extra callout points
|
|
|
|
|
|
These callouts aren't necessary to authorize the users but provide related utilities, e.g., user management.
|
|
|
|
|
|
1. `GetUserProfile`
|
|
|
2. `ListUsers`
|
|
|
3. `ChangeUserPassword`
|
|
|
|
|
|
If these callout points are missing, user management pages should be disabled.
|
|
|
|
|
|
## Implementation examples
|
|
|
|
|
|
There is an initial proposal for implementation. You can find the current development in #779.
|
... | ... | @@ -555,77 +635,3 @@ func (sa *StorkAgent) Shutdown() { |
|
|
...
|
|
|
}
|
|
|
``` |
|
|
\ No newline at end of file |
|
|
|
|
|
## Authentication hook
|
|
|
|
|
|
We decided the first hook would be an authentication hook to support login through LDAP. In the future, we want to implement more authentication hooks this way.
|
|
|
|
|
|
In general, we can split the authentication methods into two groups. The first contains solutions where the server actively mediates in the authentication process. It means that a user provides the credentials in the form presented by the server, and next, the server forwards these credentials to the authentication point. The authentication point validates the credentials and returns the user profile on success. The solutions in the second group use the delegated flow. The user initiates the authentication by clicking the button on the server page. The server redirects to the authentication point page. The user provides the credentials in the form presented by the authentication point that validates the credentials and redirects the user back to the server. The server receives the authentication token that is validated on the server-side. The token may contain the basic user profile, or the server may use it to obtain the profile from the authentication point.
|
|
|
|
|
|
The LDAP authentication belongs to the first group.
|
|
|
|
|
|
The authentication process in Stork starts on the login page. There should be displayed a list of supported authentication methods generated by the dedicated callout. Stork should also provide a flag to suppress the default authentication. The user needs to choose the preferred authentication method. Another approach is allowing only a single authentication method. If the authentication hook is loaded, it replaces the default authentication; only one authentication hook may be loaded simultaneously. The Stork should present a login form or redirect the user to the authentication point page, depending on the selected solution. The hook will be responsible for validating the form data, fetching the profile, and creating the internal user instance. This instance will be passed to the session manager. The hook should provide the possibility to log out the user too.
|
|
|
In the case of delegated authentication, the callout must generate the redirection link and handle the returned token validation.
|
|
|
|
|
|
### LDAP authentication scenario
|
|
|
|
|
|
It is a single authentication solution.
|
|
|
|
|
|
1. The server loads the hooks, including the authentication one
|
|
|
2. The user opens the login page
|
|
|
3. The UI fetches the authentication method details from the server. It displays the login form or redirection button to the authentication point.
|
|
|
4. The server calls the callout point to fetch the authentication details. If no authentication hooks were loaded, then it returns the default method. For LDAP, the login and password form is requested.
|
|
|
5. The UI presents the login and password form.
|
|
|
6. The user provides the credentials and clicks the submit button.
|
|
|
7. The `CreateSession` endpoint receives the credentials. They are passed to the hook.
|
|
|
8. The hook validates the credentials in the LDAP server. Returns an error if they are invalid.
|
|
|
9. The hook fetches the user profile from the LDAP server. It converts the data to the Stork user structure. It needs to translate the groups from the LDAP standard to the Stork indices.
|
|
|
10. The hook returns the user instance.
|
|
|
11. The server creates a session in the session manager.
|
|
|
12. The server returns the user object to the UI.
|
|
|
13. The session middleware sets the authentication cookie.
|
|
|
14. The browser receives the response, reads the cookie, and remembers it.
|
|
|
15. The UI receives the user object, saves it, and redirects to the dashboard.
|
|
|
16. The user uses Stork.
|
|
|
17. The user clicks the logout button.
|
|
|
18. The `DeleteSession` endpoint receives the request and destroys the session. It calls the logout callout point.
|
|
|
19. The UI displays the login page.
|
|
|
|
|
|
### Callout points
|
|
|
|
|
|
1. `GetAuthenticationDetails() Details`
|
|
|
|
|
|
The output structure will contain the control data for the login page:
|
|
|
|
|
|
- Authentication method name
|
|
|
- Authentication method description
|
|
|
- Authentication method icon
|
|
|
- The layout of credentials form:
|
|
|
- Username field name (username, email, identity number, etc.)
|
|
|
- Password type (standard, masked password, passwordless)
|
|
|
- Two-factor authentication field (SMS, authentication code)
|
|
|
- Captcha
|
|
|
- Remember password link
|
|
|
- Or redirect the button to the authentication point
|
|
|
|
|
|
This callout point will call only the first hook. If no hooks are registered, the core will fall back to the standard authentication.
|
|
|
|
|
|
2. `Authenticate(params users.CreateSessionParams) (*SystemUser, error)`
|
|
|
|
|
|
The authenticate callout point will be responsible for validating the credentials and preparing the user instance. It should send the data to the LDAP server. If they are correct, then the hook should fetch the user profile. It must translate the LDAP roles to the Stork groups.
|
|
|
|
|
|
This callout point will be called in the `CreateSession` REST handler. Only the callout from the first hook will be used.
|
|
|
|
|
|
3. `Deauthenticate(*SystemUser) error`
|
|
|
|
|
|
This callout point should close the user sessions in the external authentication point if necessary.
|
|
|
|
|
|
### Extra callout points
|
|
|
|
|
|
These callouts aren't necessary to authorize the users but provide related utilities, e.g., user management.
|
|
|
|
|
|
1. `GetUserProfile`
|
|
|
2. `ListUsers`
|
|
|
3. `ChangeUserPassword`
|
|
|
|
|
|
If these callout points are missing, user management pages should be disabled. |
|
|
\ No newline at end of file |