- Concepts
- Read and write information on users and organization
- Validate user secrets for authentication (password or X.509 client certificate)
- Check users permissions on an application, add and remove permissions
- Manage groups of users for applications
Users, organizations and applications can come from multiple storages and can be functionnaly isolated with realms.
Realm : base unit for sugoi, each realm is isolated from one another by permissions. Realm represents a set of sugoi objects (users, organizations, applications) managed together. Users can have read or write rights scoped to a realm.
UserStorage : storage for users and organizations in a realm. A realm can have multiple user storages. Each user storage can be at a different location and have its own user storage type (ldap, file, broker) corresponding to a store provider.
Store Provider : the way to access data. For now there are 3 store providers avalaible : local file, ldap and broker.
User : Represents an individual. It bears profile data (name, address, username...). It may also bear roles and authentification secrets and will then represent an account. A user can belong to groups.
Organization : Represents an organizational unit. An organization can have an address, secrets, suborganization... Users can belong to organizations.
Application : Represents an information system with which users and organizations can interact. Applications belong to a realm. Application is used to define roles for users on the corresponding information system with the group concept.
Group : A group is a unit of an application which contains users. The information system requesting sugoi uses groups to determine the users' status. Permissions on the information system can be managed via groups.
Users can authenticate on sugoi with basic authentication, bearer authentication or ldap authentication. For now users will have rights on the application only by using ldap authentication. The permissions are checked from groups defined in security.ldap-account-managment-url property (see configuration).
There are five profiles on sugoi permission model : admin, read and write, password and application manager. A user have a right when it belong to the corresonding ldap group. All profiles are scoped to realm except the admin group. Sugoi management groups are entirely configurable with patterns, those patterns accept the * wildcard. All the pattern configuration should be done in uppercase (as this is the way spring-security fills Authorities).
The admin group is defined via the regexp.role.admin property.
An administrator can :
- read, create, modify or delete any realms.
- read, create, modify or delete userstorages.
- do whatever the writer can do on all realms.
- request all actuator endpoints.
The realm administrator group is defined via the fr.insee.sugoi.api.regexp.role.admin.realm property. It is scoped to one realm or one userstorage.
A realm writer can :
- modify and create application and groups on the realms they manage
- do whatever an application manager can do on any application of the realm
- do whatever a password manager can do on the realms they manage
- do whatever a writer can do on the realms they manage.
The writer group is defined via the regexp.role.writer property. It is scoped to one realm.
A writer can :
- modify and create users on the realms they manage
- modify and create organizations on the realms they manage
- modify and create application and groups on the realms they manage
- do whatever a reader can do on the realms they manage.
The reader group is defined via the regexp.role.reader property. It is scoped to one realm.
A reader can :
- read users, organizations, applications and groups on the realm they are reader on.
The password manager role is defined via the regexp.role.password.manager property. It is scoped to one realm.
Password manager can initialize passwords, update password (with a given password or not) or validate a password on its realm.
The password validator role is defined via the fr.insee.sugoi.api.regexp.role.password.validator property. It is scoped to one realm or userstorage. Password validator can validate a user password on its realm and userstorage.
The application manager role is defined via the regexp.role.application.manager property.
Application manager can update an application and the associated groups (add or remove members, as well as create or delete groups). This also enable reader rights on a realm.
Creating or deleting an application requires writer privileges.
The group manager role is defined via the regexp.role.group.manager property. For example ROLE_ASI_${group}.
Group manager can add and delete users in a group.
If the group manager role is ROLE_ASI_${group}, users in ASI_admin_myapp can add or remove users from admin_myapp (in this case in any application so the group name should be application scoped).
Some groups have a self-managed property. When set to true, all members of the group can add or delete members of the group they belong to.
With this feature, the application manager can delegate the ability to manage members to the first member they add in the group. A default can be set at the application level so that all groups are then considered self-managed by default.
This provider loads realms from a file described in fr.insee.sugoi.realm.config.local.path. The file is fetched through Spring ResourceLoader.
The file is expected to contain an array of realm representations, like :
[
{
"name": "test",
"url": "/test",
"appSource": "/data/applications",
"userStorages": [
{
"name": "default",
"userSource": "/data/users",
"organizationSource": "/data/organizations",
"properties": null,
"readerType": null,
"writerType": null
}
]
}
]This provider loads realm from ldap entries, an exemple ldif file and configuration can be found in the sugoi-distribution-full-env module.
They are responsible to effectively read and write sugoi objects (users, organizations and applications) in a store.
Each object is stored in a json file located in the folder as configured in the realm.
Sugoi objects are read and written in an ldap. Attributes for each objects are described in sugoi-api-ldap-utils.
⚠️ You will need to use the provided schema for everything to work.
This allows you to send write requests to a JMS queue (tested with ActiveMQ), to be managed by the JMS Service
Those are responsible to accept Write or read requests from sugoi users.
Simple http rest services.
Listen to message on a JMS queue, made to work well with JMS write provider
Sometimes user informations that are not stored in the sugoi realm are needed. It can be for instance a logo or an information on another directory. If these informations are free to read it is possible to use the SeeAlso functionnality to fetch those informations.
The SeeAlso functionnality will add attributes to user attributes when reading a seealso link. SeeAlso links can be described as :
url|suboject|attributetoset
with url being the url of the resource to fetch, suboject an instruction to take a subobject of the resource and attributetoset the name of the new attribute which will be added to the user attributes. Depending on the protocol defined in the url a different parser will be used. The parsers are pluggable.
The resource fetch should be a string or a list of strings. If the resouce can't be retrieved or parsed the attribute will be created but set to null.
To enable the SeeAlso functionality a realm property as to be set : seealso_attributes (see realm-configuration for more details). It will enable looking for SeeAlso links in the named attribute. A good default for this property is seealso_attributes: SeeAlso . It is now possible to add SeeAlso links in the SeeAlso attribute of the users. All the links in this attribute will be parse as SeeAlso links.
Two parsers exist for now but other can be added (see a future Development documentation). They have to be added as a module to the application.
If the protocol is http or https then the resource will be considered to be a valid json data.
The url must be a valid http url to a webservice openly readable. The object describe how to parse the json with node separated by dots and array values chosen with []
A valid seealso would be :
http://example.org/toto|items[3].name|http_string
The attribute http_string of the user would be set to the value of the name of the third item of the resource at http://example.org/toto
If the protocol is ldap, url is expected to be the value of a ldap url without attribute. The ldap server should be openly readable. The suboject should be the name of the attribute we want to get from the ldap resource.
A valid seealso would be :
ldap://localhost:10389/uid=testc,ou=contacts,ou=clients_domaine1,o=insee,c=fr|cn|ldap_string
The user attribute ldap_string would be set to the cn of the testc resource on localhost:10389 ldap server.
On /reinit-password, /change-password and /send-login endpoints, Sugoi can be configured to POST a message on an external webservice. See Webhook configuration to define the uri of the webservice, how to authenticate or how to choose the default template and Realm configuration to see how to define a template by realm.
Several webservices can be configured. The webservice is chosen by the user by specifying a TAG in their request. If no tag is specified the webservice configured for the tag MAIL will be used by default.
A possible usecase of these notifications is to call a webservice that send email when a password is changed.
Reserved keywords are template keywords that the user won't be able to set or that will have a default value if not set. Those are :
- mail : can be set as a template property but if not, the mail of the user on which the request is made will be taken as default.
- userId : is the name of the user on which the request is done, cannot be changed
Sometimes we need to define a field on a user at the userstorage level. For example, we need all users to have the field "userstoragedescription": "mydescription". Instead of adding the field userstoragedescription on each user in the store we can add it directly on the configuration of the userstorage via the userstorage property (see user_us_defined_attributes). When the user is fetch by username, this field is added in the attributes map of the user if it is not already existing on the user.
This generic field can also be customized with data specific to the user. For example, we want all users to have a field "complicatedname" which is a combination of the personal title, first name and surname of a user. The userstorage defined attribute can be defined as a pattern of field on the user that are defined as String in the usermapping (see user mapping): "complicatedname": "The name is :