rooty/fab-manager
1
0
Fork 0
mirror of https://github.com/LaCasemate/fab-manager.git synced 2025-02-20 14:54:15 +01:00
Code Issues Releases Activity

updated documentation

Browse Source
This commit is contained in:
Sylvain 2020-04-14 10:05:48 +02:00
parent bc9b2f4c36
commit 480d763e96
4 changed files with 70 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@ -102,7 +102,6 @@ Fab-manager can be connected to a [Single Sign-On](https://en.wikipedia.org/wiki
Currently OAuth 2 is the only supported protocol for SSO authentication.
For an example of how to use configure a SSO in Fab-manager, please read [sso_with_github.md](doc/sso_with_github.md).
Developers may find information on how to implement their own authentication protocol in [sso_authentication.md](doc/sso_authentication.md).
<a name="known-issues"></a>
## Known issues

11
doc/README.md
View File

@ -4,7 +4,12 @@
The following guide describes what you can do and how to use Fab-manager.
- [Français](fr/guide_utilisation_fab_manager_v4.3.pdf)
### General documentation
Translators, contributors, developers and system administrators should start by reading this document.
- [Read first](../README.md)
### System administrator
The following guides are designed for the people that perform software maintenance.
- [Setup and update a production environment](production_readme.md)
- [Configuring the environment variables](environment.md)
@ -15,14 +20,18 @@ The following guide describes what you can do and how to use Fab-manager.
- [Connecting a SSO using oAuth 2.0](sso_with_github.md)
- [Upgrade from Fab-manager v1.0](upgrade_v1.md)
#### Upgrades procedures
- [PostgreSQL](postgres_upgrade.md)
- [ElasticSearch](elastic_upgrade.md)
### Developer's documentation
The following guides should help those who want to contribute to the code.
#### How to setup a development environment
- [With docker-compose](development_readme.md)
- [With vagrant](virtual-machine.md)
#### Externals
@ -30,8 +39,6 @@ The following guide describes what you can do and how to use Fab-manager.
- [Changing the database system](postgresql_readme.md)
- [Create a new SSO method](sso_authentication.md)
#### Diagrams
- [Database diagram](database.svg)

144
doc/sso_authentication.md
View File

@ -1,144 +0,0 @@
# How to add an authentication method to the Fab-manager ?
First, take a look at the [OmniAuth list of strategies](https://github.com/intridea/omniauth/wiki/List-of-Strategies) for the Strategy or Developer Strategy you want to add to the Fab-manager.
For this guide, we will consider you want to add a generic *developer strategy*, like LDAP.
Create the OmniAuth implementation ( **lib/omni_auth/strategies/ldap_provider.rb** )
```ruby
# first require the OmniAuth gem you added to your Gemfile (see the link above for a list of gems)
require 'omniauth-ldap'
module OmniAuth
module Strategies
# in the class name, replace Ldap with the kind of authentication you are implementing
class SsoLdapProvider < OmniAuth::Strategies::LDAP
# implement the logic here, see the gem specific documentation for more details
end
end
end
```
Create the ActiveRecord models ( **from the terminal** )
```bash
# in the models names, replace Ldap with the kind of authentication you are implementing
# replace ldap_fields with the fields you need for implementing LDAP or whatever you are implementing
rails g model LdapProvider ...ldap_fields
rails g model LdapMapping ldap_provider:belongs_to local_field:string local_model:string ...ldap_fields
```
Complete the Provider Model ( **app/model/ldap_provider.rb** )
```ruby
class LdapProvider < ApplicationRecord
has_one :auth_provider, as: :providable
has_many :ldap_mappings, dependent: :destroy
accepts_nested_attributes_for :ldap_mappings, allow_destroy: true
# return the fields you want to protect from being directly managed by the Fab-manager, typically mapped fields
def protected_fields
fields = []
ldap_mappings.each do |mapping|
fields.push(mapping.local_model+'.'+mapping.local_field)
end
fields
end
# return the link, that the current user will have to follow, to edit his profile on the SSO
def profile_url
# you can also create a profile_url field in the Database model
end
end
```
Whitelist your implementation's fields in the controller ( **app/controllers/api/auth_providers_controller.rb** )
```ruby
class API::AuthProvidersController < API::ApiController
...
private
def provider_params
if params['auth_provider']['providable_type'] == DatabaseProvider.name
...
elsif if params['auth_provider']['providable_type'] == LdapProvider.name
params.require(:auth_provider).permit(:name, :providable_type, providable_attributes: [
# list here your LdapProvider model's fields, followed by the mappings :
ldap_mappings_attributes: [
:id, :local_model, :local_field, ...
# add your other customs LdapMapping fields, don't forget the :_destroy symbol if
# you want your admin to be able to remove mappings
]
])
end
end
end
```
List the fields to display in the JSON API view ( **app/views/api/auth_providers/show.json.jbuilder** )
```ruby
json.partial! 'api/auth_providers/auth_provider', auth_provider: @provider
...
if @provider.providable_type == LdapProvider.name
json.providable_attributes do
json.extract! @provider.providable, :id, ... # list LdapProvider fields here
json.ldap_mappings_attributes @provider.providable.ldap_mappings do |m|
json.extract! m, :id, :local_model, :local_field, ... # list LdapMapping fields here
end
end
end
```
Configure the initializer ( **config/initializers/devise.rb** )
```ruby
require_relative '../../lib/omni_auth/omni_auth'
...
elsif active_provider.providable_type == LdapProvider.name
config.omniauth OmniAuth::Strategies::SsoLdapProvider.name.to_sym, # pass here the required parameters, see the gem documentation for details
end
```
Finally you have to create an admin interface with AngularJS:
- **app/assets/templates/admin/authentifications/_ldap.html.erb** must contains html input fields (partial html form) for the LdapProvider fields configuration
- **app/assets/templates/admin/authentifications/_ldap_mapping.html.erb** must contains html partial to configure the LdapMappings, see _oauth2_mapping.html.erb for a working example
- **app/assets/javascript/controllers/admin/authentifications.coffee**
```coffeescript
## list of supported authentication methods
METHODS = {
...
'LdapProvider' : 'LDAP' # add the name of your ActiveRecord model class here as a hash key, associated with a human readable name as a hash value (string)
}
Application.Controllers.controller "newAuthentificationController", ...
$scope.updateProvidable = ->
...
if $scope.provider.providable_type == 'LdapProvider'
# you may want to do some stuff to initialize your provider here
$scope.registerProvider = ->
...
# === LdapProvider ===
else if $scope.provider.providable_type == 'LdapProvider'
# here you may want to do some data validation
# then: save the settings
AuthProvider.save auth_provider: $scope.provider, (provider) ->
# register was a success, display a message, redirect, etc.
```
And to include this interface into the existing one ( **app/assets/templates/admin/authentifications/edit.html.erb**)
```html
<form role="form" name="providerForm" class="form-horizontal" novalidate>
...
<!-- Add the following ng-include inside the providerForm -->
<ng-include src="'<%= asset_path 'admin/authentifications/_ldap.html'%>'" ng-if="provider.providable_type == 'LdapProvider'"></ng-include>
</form>
```
Do not forget that you can find examples and inspiration in the OAuth 2.0 implementation.

61
doc/upgrade_v1.md Normal file
View File

@ -0,0 +1,61 @@
# Upgrade from v1.0.0
Steps to follow:
- Dump database of v1
- Make a gzipped tarball of public/uploads
- Install Fab-manager v4.3.4+
- Restore the DB dump in the new postgres instance
- Open a psql shell, then:
```sql
TRUNCATE schema_migrations;
INSERT INTO schema_migrations (version)
VALUES
('20140409083104'),
('20140414141134'),
('20140703231208'),
('20140703235739'),
('20140703233420'),
('20140703233942'),
('20140409083610'),
('20140409153915'),
('20140410101026'),
('20140622122944'),
('20150108082541'),
('20140415123625'),
('20140522181148'),
('20140526144327'),
('20140410140516'),
('20140623023557'),
('20140410162151'),
('20140411152729'),
('20140415104151'),
('20140528134944'),
('20140528140257'),
('20140416130838'),
('20140513152025'),
('20140422085949'),
('20141217172843'),
('20140522115617'),
('20140522175539'),
('20140522175714'),
('20140522180032'),
('20140522180930'),
('20140522181011'),
('20140523083230'),
('20140527092045'),
('20150218154032'),
('20140603084413'),
('20140604094514'),
('20140622121724'),
('20140710144142'),
('20140711084809'),
('20140717143735'),
('20140710144427'),
('20140710144610'),
('20200408101654');
```
- `rails db:migrate`
- `rails fablab:maintenance:migrate_v1_notifications`
- Extract the tarball of the uploads in the new instance folder
- Start the new instance and delete the old one