This is an automated email from the ASF dual-hosted git repository. rombert pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git
The following commit(s) were added to refs/heads/master by this push: new c5236f96 oidc-rp: refresh documentation c5236f96 is described below commit c5236f969e7f36173b50955daef60cc8e5802a82 Author: Robert Munteanu <romb...@apache.org> AuthorDate: Mon Jul 3 17:02:12 2023 +0300 oidc-rp: refresh documentation --- org.apache.sling.servlets.oidc-rp/README.md | 94 +++++++++++------------------ 1 file changed, 36 insertions(+), 58 deletions(-) diff --git a/org.apache.sling.servlets.oidc-rp/README.md b/org.apache.sling.servlets.oidc-rp/README.md index 6e37ac21..deb24613 100644 --- a/org.apache.sling.servlets.oidc-rp/README.md +++ b/org.apache.sling.servlets.oidc-rp/README.md @@ -1,5 +1,25 @@ # Apache Sling OpenID Connect Relying Party support bundle +<Warning> +This bundle is under development, do not use in production. +</Warning> + +## Introduction + +This bundle add support for Sling-based applications to function as +[Open ID connect](https://openid.net/developers/how-connect-works/) relying parties. Its main +objective is to simplify access to user and access tokens in a secure manner. + +## Whiteboard graduation TODO + +- bundle/package should probably be org.apache.sling.extensions.oidc, as the primary entry point is the Java API +- clarify Java API and allow extracting both id and access tokens +- make use of refresh tokens +- document usage for the supported OIDC providers; make sure to explain this is _not_ an authentication handler +- provide a sample content package and instructions how to use +- review to see if we can use more of the Nimbus SDK, e.g. enpodints discovery, token parsing +- review security best practices + ## Prerequisites ### Client registration @@ -12,74 +32,40 @@ Validated providers: ## Sling Starter Prerequisites -A number of additional bundles need to be added to the Sling Starter. - -```diff -diff --git a/src/main/features/app/starter.json b/src/main/features/app/starter.json -index 9c9231f..18c1586 100644 ---- a/src/main/features/app/starter.json -+++ b/src/main/features/app/starter.json -@@ -3,6 +3,34 @@ - { - "id":"org.apache.sling:org.apache.sling.starter.content:1.0.12", - "start-order":"20" -+ }, -+ { -+ "id":"com.nimbusds:oauth2-oidc-sdk:9.35", -+ "start-order":"20" -+ }, -+ { -+ "id":"com.nimbusds:nimbus-jose-jwt:9.22", -+ "start-order":"20" -+ }, -+ { -+ "id":"com.nimbusds:content-type:2.2", -+ "start-order":"20" -+ }, -+ { -+ "id":"com.nimbusds:lang-tag:1.6", -+ "start-order":"20" -+ }, -+ { -+ "id":"org.apache.servicemix.bundles:org.apache.servicemix.bundles.jcip-annotations:1.0_2", -+ "start-order":"20" -+ }, -+ { -+ "id":"net.minidev:json-smart:2.4.8", -+ "start-order":"20" -+ }, -+ { -+ "id":"net.minidev:accessors-smart:2.4.8", -+ "start-order":"20" - } - ] - } - -``` +A number of additional bundles need to be added to the Sling Starter, see the feature model definition at src/main/features/main.json . ### Deployment and configuration -After deploying the bundle using `mvn package sling:install` go to http://localhost:8080/system/console/configMgr and create a new configuration instance for _OpenID Connect connection details_. +After deploying the bundle using `mvn package sling:install` go to http://localhost:8080/system/console/configMgr and create a new configuration factory instance for _OpenID Connect connection details_. Write down the name property, we'll refer to it as `$CONNECTION_NAME`. ### Kicking off the process Ensure you are logged in. -- navigate to http://localhost:8080/system/sling/oidc/entry-point?redirect=/bin/browser.html +- navigate to http://localhost:8080/system/sling/oidc/entry-point?c=$CONNECTION_NAME&redirect=/bin/browser.html - you will be redirect to the identity provider, where you will need authenticate yourself and authorize the connection - you will be redirected to the composum browser -At this point you need to can navigate to /home/users/${USERNAME}/oidc-tokens/${CONNECTION_NAME} and you will see the stored token and expiry date (if available ). - +At this point you can navigate to /home/users/${USERNAME}/oidc-tokens/${CONNECTION_NAME} and you will see the stored access token. ### Local development setup #### Keycloak +##### Use existing test files + +Note that this imports the test setup with a single user with a _redirect_uri_ set to _http://localhost*_, which can be a security issue. + +``` +$ docker run --rm --volume $(pwd)/src/test/resources/keycloak-import:/opt/keycloak/data/import -p 8081:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:20.0.3 start-dev --import-realm +``` + +##### Manual setup + 1. Launch Keycloak locally ``` -$ docker run --rm --volume (pwd)/keycloak-data:/opt/keycloak/data -p 8081:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:20.0.3 start-dev +$ docker run --rm --volume $(pwd)/keycloak-data:/opt/keycloak/data -p 8081:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:20.0.3 start-dev ``` 2. Create test realm @@ -133,7 +119,7 @@ scopes: openid #### Obtaining the tokens - navigate to http://localhost:8080/system/sling/login and login as admin/admin -- go to http://localhost:8080/system/sling/oidc/entry-point?redirect=/bin/browser.html/home/users +- go to http://localhost:8080/system/sling/oidc/entry-point?c=keycloak&redirect=/bin/browser.html/home/users - complete the login flow - navigate in composum to the user name of the admin user and verify that the 'oidc-tokens' node contains a keycloak node with the respective access_token and refresh_token properties @@ -142,11 +128,3 @@ scopes: openid ``` $ docker run --rm --volume (pwd)/keycloak-data:/opt/keycloak/data -p 8081:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:20.0.3 export --realm sling --users realm_file --file /opt/keycloak/data/export/sling.json ``` - -## Whiteboard graduation TODO - -- bundle/package should probably be org.apache.sling.extensions.oidc-rp, as the primary entry point is the Java API -- document usage; make sure to explain this is _not_ an authentication handler -- provide a sample content package and instructions how to use -- review to see if we can use more of the Nimbus SDK, e.g. enpodints discovery, token parsing -- review security best practices