[GitHub] [sling-whiteboard] cmrockwell commented on a change in pull request #62: Saml2 auth handler/upgrade sling12 open samlv4 java11

[GitBox <gi...@apache.org>]

cmrockwell commented on a change in pull request #62:
URL: https://github.com/apache/sling-whiteboard/pull/62#discussion_r448594429



##########
File path: saml-handler/README.md
##########
@@ -1,43 +1,140 @@
 # Apache Sling SAML2 Handler (NOT FOR PRODUCTION)
 
-This project is intended to be a contribution to the [Apache Sling](https://sling.apache.org) project;
- it has a SAML2 Service Provider Authentication Handler and the associated SAML2 servlets and utilities. It is a work in progress and not production ready!
+This contribution to the [Apache Sling](https://sling.apache.org) project;
+ provides a SAML2 Web Profile Service Provider Authentication. 
+
 
 ## Overview
 https://en.wikipedia.org/wiki/SAML_2.0
 
 * The SAMLRequest uses HTTP Redirect Binding, and the contained Authn Request object instructs the IDP to use HTTP Post Binding. 
 
 ![](src/main/resources/Saml2SP.png)
- 
-## Features  
-Sling applications to authenticate users against Identity Providers (idp) 
-such as Keycloak or Shibboleth using SAML2 protocols.
+   
+Sling applications may authenticate users against an Identity Provider (idp) 
+such as Keycloak Server or Shibboleth IDP.
+
+### Requirements
+- Java 11
+- Sling 11 or 12
+- The bundle will not activate without [org.apache.jackrabbit.oak-auth-external](https://mvnrepository.com/artifact/org.apache.jackrabbit/oak-auth-external)
+- An external SAML2 identity provider
+
+
+
+### User Management
+User management is based on the OSGi bundle configuration and SAML2 Assertion    
+  - Upon successful authentication, a user is created
+  - The user may be added to a JCR group membership under certain conditions: 
+    - An OSGI config is set `saml2groupMembershipAttr` with the value of the group membership attribute
+    - The users' assertion contains an attribute where the key is value of `saml2groupMembershipAttr` and the attribute value is an existing JCR group.
+   Note that if the assertion group membership attribute value contains values that are not existing JCR groups, then the value is ignored.   
+  - Other user attributes from the assertion may be configured. This allows profile properties such as given name, family name, email, and phone which are leased by the Identity Provider and added to the JCR User's properties. Such attributes are configured by setting `syncAttrs` to the corresponding attribute keys.      
+   
+
+
+
+## Localhost Setup
+Procedure for localhost testing
+
+### Start and Configure an External Identity Provider 
+1. Start a Keycloak Server 
+`docker run -p 8484:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:10.0.2`
+2. Login using http://localhost:8484/auth/admin/ 

Review comment:
       I tried importing the realm. Maybe my docker skills were not enough to get it working. Every time it complained that the import file could not be found. Otherwise, the jboss docker image seemed to work great. However in my experience, some of the keycloak docker instances were quite temporary. Instances older than a week would not start for me. So as I developed this, I sometimes used a standalone instance. 




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org