cmrockwell commented on a change in pull request #62: URL: https://github.com/apache/sling-whiteboard/pull/62#discussion_r445147208
########## 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.  - -## 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/ + - username: admin, password: admin +3. Configure a Realm + - Click "Add Realm" + - Select the file located at `saml-handler/src/main/resources/sling-realm-export.json` + +Note. The preconfigured realm contains configuration for the client and the groups, but does not contain users. +4. Add user(s) + - Select Users under the "Sling" Realm +  + - Set user attributes +  + - Set user password +  + - Set user groups +  + + + + +### Sling SAML2 Service Provider Setup + +1. Start Sling +2. Use Felix "/system/console" to install bundle [org.apache.jackrabbit.oak-auth-external](https://mvnrepository.com/artifact/org.apache.jackrabbit/oak-auth-external) corresponding to the JCR Oak version in your instance (e.g. 1.26.0) +3. Run `mvn clean install -P autoInstallBundle` to the SAML2 Bundle. Verify the state is Active +4. Use Composum to install the localhost test package "src/main/resources/localhostExample-1.zip" Review comment: For JCR Packages I can do as you suggest. I was just about to add another binary of a JKS to test signing and encryption. Similar to this https://bitbucket.org/srasmusson/webprofile-ref-project-v3/src/master/src/main/resources/ Used here https://bitbucket.org/srasmusson/webprofile-ref-project-v3/src/master/src/main/java/no/steras/opensamlbook/sp/SPCredentials.java I want to use this JKS for unit tests. I prefer to keep the JKS out of the JCR repository instead getting it from the file system. What would you suggest? ---------------------------------------------------------------- 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: us...@infra.apache.org
