feat: RBAC + SAML support

docs/admins_docs.md

@@ -21,7 +21,12 @@
 - [18. Disable encoding and show only original file](#18-disable-encoding-and-show-only-original-file)
 - [19. Rounded corners on videos](#19-rounded-corners)
 - [20. Translations](#20-translations)
-- [21. How to change the video frames on videos](#21-fames)
+- [21. How to change the video frames on videos](#21-how-to-change-the-video-frames-on-videos)
+- [22. Role-Based Access Control](#22-role-based-access-control)
+- [23. SAML setup](#23-saml-setup)
+- [24. Identity Providers setup](#24-identity-providers-setup)
+
+
 
 ## 1. Welcome
 This page is created for MediaCMS administrators that are responsible for setting up the software, maintaining it and making modifications.
@@ -861,3 +866,110 @@ By default while watching a video you can hover and see the small images named s
 
 After that, newly uploaded videos will have sprites generated with the new number of seconds.
 
+
+
+## 22. Role-Based Access Control
+
+By default there are 3 statuses for any Media that lives on the system, public, unlisted, private. When RBAC support is added, a user that is part of a group has access to media that are published to one or more categories that the group is associated with. The workflow is this:
+
+
+1. A Group is created
+2. A Category is associated with the Group
+3. A User is added to the Group
+
+Now user can view the Media even if it is in private state. User also sees all media in Category page
+
+When user is added to group, they can be set as Member, Contributor, Manager. 
+
+- Member: user can view media that are published on one or more categories that this group is associated with
+- Contributor: besides viewing, user can also edit the Media in a category associated with this Group. They can also publish Media to this category
+- Manager: same as Contributor for now
+
+Use cases facilitated with RBAC:
+- viewing a Media in private state: if RBAC is enabled, if user is Member on a Group that is associated with a Category, and the media is published to this Category, then user can view the media
+- editing a Media: if RBAC is enabled, and user is Contributor to one or more Categories, they can publish media to these Categories as long as they are associated with one Group
+- viewing all media of a category: if RBAC is enabled, and user visits a Category, they are able to see the listing of all media that are published in this category, independent of their state, provided that the category is associated with a group that the user is member of
+- viewing all categories associated with groups the user is member of: if RBAC is enabled, and user visits the listing of categories, they can view all categories that are associated with a group the user is member
+
+How to enable RBAC support: 
+
+```
+USE_RBAC = True
+```
+
+on `local_settings.py` and restart the instance. 
+
+
+## 23. SAML setup
+SAML authentication is supported along with the option to utilize the SAML response and do useful things as setting up the user role in MediaCMS or participation in groups. 
+
+To enable SAML support, edit local_settings.py and set the following options:
+
+```
+USE_RBAC = True
+USE_SAML = True
+USE_IDENTITY_PROVIDERS = True
+
+USE_X_FORWARDED_HOST = True
+SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
+SECURE_SSL_REDIRECT = True
+CSRF_COOKIE_SECURE = True
+SESSION_COOKIE_SECURE = True
+
+SOCIALACCOUNT_ADAPTER = 'saml_auth.adapter.SAMLAccountAdapter'
+SOCIALACCOUNT_PROVIDERS = {
+    "saml": {
+        "provider_class": "saml_auth.custom.provider.CustomSAMLProvider",
+    }
+}
+```
+
+
+To set a SAML provider:
+
+- Step 1: Add SAML Identity Provider
+1. Navigate to Admin panel
+2. Select "Identity Provider"
+3. Configure as follows:
+   - **Provider**: saml
+   - **Provider ID**: an ID for the provider
+   - **IDP Config Name**: a name for the provider
+   - **Client ID**: the identifier that is part of the login, and that is shared with the IDP.
+   - **Site**: Set the default one
+
+- Step 2: Add SAML Configuration
+Select the SAML Configurations tab, create a new one and set:
+
+1. **IDP ID**: Must be a URL
+2. **IDP Certificate**: x509cert from your SAML provider
+3. **SSO URL**: 
+4. **SLO URL**: 
+5. **SP Metadata URL**: The metadata URL that the IDP will utilize. This can be https://{portal}/saml/metadata and is autogenerated by MediaCMS
+
+- Step 3: Set other Options
+1. **Email Settings**:
+   - `verified_email`: When enabled, emails from SAML responses will be marked as verified
+   - `Remove from groups`: When enabled, user is removed from a group after login, if they have been removed from the group on the IDP
+2. **Global Role Mapping**: Maps the role returned by SAML (as set in the SAML Configuration tab) with the role in MediaCMS
+3. **Group Role Mapping**: Maps the role returned by SAML (as set in the SAML Configuration tab) with the role in groups that user will be added
+4. **Group mapping**: This creates groups associated with this IDP. Group ids as they come from SAML, associated with MediaCMS groups
+5. **Category Mapping**: This maps a group id (from SAML response) with a category in MediaCMS
+
+## 24. Identity Providers setup
+
+A separate Django app identity_providers has been added in order to facilitate a number of configurations related to different identity providers. If this is enabled, it gives the following options:
+
+- allows to add an Identity Provider through Django admin, and set a number of mappings, as Group Mapping, Global Role mapping and more. While SAML is the only provider that can be added out of the box, any identity provider supported by django allauth can be added with minimal effort. If the response of the identity provider contains attributes as role, or groups, then these can be mapped to MediaCMS specific roles (advanced user, editor, manager, admin) and groups (rbac groups)
+- saves SAML response logs after user is authenticated (can be utilized for other providers too)
+- allows to specify a list of login options through the admin (eg system login, identity provider login)
+
+
+to enable the identity providers, set the following setting on `local_settings.py`:
+
+
+```
+USE_IDENTITY_PROVIDERS = True
+```
+
+Visiting the admin, you will see the Identity Providers tab and you can add one. 
+