added note about kc native orgs feature (#229)

README.md

@@ -1,4 +1,4 @@
-> :rocket: **Try it for free** in the new Phase Two [keycloak managed service](https://phasetwo.io/?utm_source=github&utm_medium=readme&utm_campaign=keycloak-orgs). See the [announcement and demo video](https://phasetwo.io/blog/self-service/) for more information.
+> :rocket: **Try it for free** in the new Phase Two [keycloak managed service](https://phasetwo.io/?utm_source=github&utm_medium=readme&utm_campaign=keycloak-orgs). Go to [Phase Two](https://phasetwo.io/) for more information.
 
 # Organizations for Keycloak
 
@@ -8,6 +8,8 @@ This project intends to provide a range of Keycloak extensions focused on solvin
 
 The extensions herein are used in the [Phase Two](https://phasetwo.io) cloud offering, and are released here as part of its commitment to making its [core extensions](https://phasetwo.io/docs/introduction/open-source) open source. Please consult the [license](COPYING) for information regarding use.
 
+> :exclamation: See [our note regarding Keycloak's upcoming organizations feature](./docs/note-keycloak-organizations-feature.md).
+
 ## Contents
 
 - [Organizations for Keycloak](#organizations-for-keycloak)
@@ -45,6 +47,9 @@ Other approaches that we tried and decided against were:
 
 But each of these approaches had trade-offs of scale or frailty we found undesirable or unacceptable to meet our requirements. Instead, we opted to make Organizations, and their Invitations, Roles and Memberships first-class entities in Keycloak.
 
+We recently did a presentation at Keycloak DevDay 2024 on the features of the keycloak-orgs extension. Watch the full video for an introduction and more information about what is possible
+[![Multi-Tenancy in Keycloak](https://img.youtube.com/vi/DNq51wWw3F4/0.jpg)](https://www.youtube.com/watch?v=DNq51wWw3F4)
+
 ### Definitions
 
 - **Organizations** are "tenants" or "customers" as commonly used. A Realm can have multiple Organizations.
@@ -57,47 +62,30 @@ But each of these approaches had trade-offs of scale or frailty we found undesir
 
 The easiest way to get started is our [Docker image](https://quay.io/repository/phasetwo/phasetwo-keycloak?tab=tags). Documentation and examples for using it are in the [phasetwo-containers](https://github.com/p2-inc/phasetwo-containers) repo. The most recent version of this extension is included.
 
-## Building
-
-Checkout this project and run `mvn package`, which will produce a jar in the `target/` directory.
-
-The build uses `keycloak-testsuite-utils` for the unit tests. If you want to run the tests, you'll need to install Keycloak from source locally, as the test utility never gets published to maven central by the Keycloak team. To build Keycloak from source you must check out the tag of the Keycloak version you are using and then build (do this in a separate directory):
+## Building and testing
 
-```bash
-KC_VERSION=21.1.1
-git clone https://github.com/keycloak/keycloak
-git fetch origin --tags
-git checkout $KC_VERSION
-mvn clean install -DskipTests
-```
-
-And then run the build with the tests using the `test` profile:
+Checkout this project and run `mvn clean install`, which will build the source, run all unit/integration tests, and produce a jar in the `target/` directory.
 
-```bash
-mvn clean install -Ptest
-```
+### Cypress tests
 
-## Cypress Test
 For more information you can refer to [cypress-tests](./docs/cypress-tests.md).
 
-
 ## Installation
 
-The maven build uses the shade plugin to package a fat-jar with all dependencies, except for the [`keycloak-admin-client`](https://mvnrepository.com/artifact/org.keycloak/keycloak-admin-client). Put the `keycloak-orgs` jar and `keycloak-admin-client` jar (that corresponds to your Keycloak version) in your `provider` (for Quarkus-based distribution) or in `standalone/deployments` (for Wildfly, legacy distribution) directory and restart Keycloak. It is unknown if these extensions will work with hot reloading using the legacy distribution.
+The maven build only produces a jar of the code here, and some additional libraries are necessary when using this library. If you are intending to use this library outside of the [Phase Two Docker image](https://quay.io/repository/phasetwo/phasetwo-keycloak), please consult the `pom.xml` file in the [phasetwo-containers repo](https://github.com/p2-inc/phasetwo-containers/blob/main/libs/pom.xml) for more information on what is required. Furthermore, there are some uses of the `keycloak-admin-client` by this library. Because of the way Quarkus does augmentation of this dependency, it is necessary to include this when building Keycloak itself. Our image has these changes, but they will [never be included](https://github.com/keycloak/keycloak/issues/25589) in the default Keycloak image. We encourage you to either use our [base Docker image](https://quay.io/repository/phasetwo/keycloak-crdb) that includes this, or see the [`pom.xml` diffs](https://github.com/keycloak/keycloak/compare/24.0.3...p2-inc:keycloak:24.0.3_crdb#diff-398bf5e6ab6c70cc2fa4c088f20e15b2a3777e8e67b82afe65b5784226bc07cb) for an example of how to do it yourself.
 
 During the first run, some initial migrations steps will occur:
 
-- Database migrations will be run to add the tables for use by the JPA entities. These have been tested with SQL Server,
-  MySQL, MariaDB, H2, and Postgres. Other database types may fail.
+- Database migrations will be run to add the tables for use by the JPA entities. These have been tested with SQL Server, MySQL, MariaDB, H2, and Postgres. Other database types may fail.
 - Initial `realm-management` client roles (`view-organizations` and `manage-organizations`) will be be added to each realm.
 
 ### Admin UI
 
-If you are using the extension as bundled in the [Docker image](https://quay.io/repository/phasetwo/phasetwo-keycloak?tab=tags) or by building our [Admin UI theme](https://github.com/p2-inc/keycloak-ui), you must take an additional step in order to show that theme. In the Admin Console UI, go to the *Realm Settings* -> *Themes* page and select `phasetwo.v2`. Then, the "Organizations" section will be available in the left navigation. Because of a quirk in Keycloak, if you are logging in to the `master` realm, the theme must be set in *that* realm, rather than the realm you wish to administer.  
+If you are using the extension as bundled in the [Docker image](https://quay.io/repository/phasetwo/phasetwo-keycloak) or by building our [Admin UI theme](https://github.com/p2-inc/keycloak-ui), you must take an additional step in order to show that theme. In the Admin Console UI, go to the *Realm Settings* -> *Themes* page and select `phasetwo.v2`. Then, the "Organizations" section will be available in the left navigation. Because of a quirk in Keycloak, if you are logging in to the `master` realm, the theme must be set in *that* realm, rather than the realm you wish to administer.  
 
 ### Compatibility
 
-Although it has been developed and working since Keycloak 9.0.0, the extensions are currently known to work with Keycloak > 17.0.0. Other versions may work also. Please file an issue if you have successfully installed it with prior versions. Additionally, because of the fast pace of breaking changes since Keycloak "X" (Quarkus version), we don't make any guaranteed that this will work with any version other than it is packaged with in the [Docker image](https://quay.io/repository/phasetwo/phasetwo-keycloak?tab=tags).
+Although it has been developed and working since Keycloak 9.0.0, the extensions are currently known to work with Keycloak > 17.0.0. Other versions may work also. Additionally, because of the fast pace of breaking changes since Keycloak "X" (Quarkus version), we don't make any guaranteed that this will work with any version other than it is packaged with in the [Docker image](https://quay.io/repository/phasetwo/phasetwo-keycloak).
 
 ## Extensions
 
@@ -173,7 +161,7 @@ For more information you can refer to: [Import/Export](./docs/import-export.md)
 
 ### Mappers
 
-There is currently a single OIDC mapper that adds Organization membership and roles to the token. The format of the addition to the token is
+There are currently two OIDC mapper that adds either Organization attributes or Organization membership and roles to the token. An example of the format of the membership addition to the token is:
 
 ```json
   "organizations": {

docs/import-export.md

@@ -1,4 +1,3 @@
-> :warning: **This feature is EXPERIMENTAL**: Do not use for production purposes!
 
 # Import/Export
 
@@ -354,4 +353,4 @@ E.q.:
 ```
 curl --location 'https://{$fqdn}/auth/realms/{{$realm}}/orgs/export?exportMembersAndInvitations=true' \
 --header 'Authorization: Bearer {{$access_token}}'
-```
+```

docs/note-keycloak-organizations-feature.md

@@ -0,0 +1,19 @@
+
+# Note regarding Keycloak's upcoming organizations feature
+
+The Keycloak team at RedHat has [announced](https://github.com/keycloak/keycloak/discussions/23948) that they will be building an Organizations feature into the core product. We have previously offered to change our license and donate our extension to the project, but this was not considered. We participated in some of the public discussions around this feature, as well as provided feedback on their product features privately.
+
+Work has begun, and they plan to [release](https://github.com/keycloak/keycloak/issues/28609) some base features with `experimental` support in Keycloak `25`. They expect a full feature set and promotion to `preview` by Keycloak `26`. There are a few GitHub issues that indicate the features they plan to release, but there is not a comprehensive requirements or product feature plan available publicly.
+
+It has been our goal since building this extension to have this approach to multi-tenancy built into Keycloak, and we have proven through many customers/user that is serves a real need. We're excited to see what they will build, and are flattered they have used our extension for inspiration.
+
+We have several hundred customers and users of this extension, and there have been many asking about the future of this extension, given the above. We've put together these notes, and will continue to update them as we learn more.
+
+- First of all, **this extension is not going away**. In addition to the fact we have long-term support agreements with many of our customers, we also don't currently have a picture of what Keycloak's implementation will ultimately look like.
+- We continue to believe that our (Phase Two's) value is in making Keycloak easy to use, primarily for an audience that is using it as a CIAM tool for enterprise SaaS applications. We have tailored the feature set to that audience, and will continue to build out tools on top of our own organizations extension, such as the [admin portal](https://github.com/p2-inc/phasetwo-admin-portal) and [IdP wizards](https://github.com/p2-inc/idp-wizard) to facilitate making your app enterprise-ready quickly.
+- We plan **not** to enable native Keycloak organizations in our hosted product, and it will be set (in env vars) off in our Docker images.
+- We have initiated a project to move our organizations (and other) admin UI tools **outside** of the Keycloak Admin UI. In addition to proving very time consuming because of the pace of breaking changes, we realized that we can iterate faster for customer value by building our own admin UI. More information on that coming soon.
+- We will continue to participate in discussions with RedHat and the Keycloak maintainers to advocate for our customers' needs and the features we have proven over >3 years.
+- **IF** there is eventually sufficient feature parity between native Keycloak organizations and this extension, we will provide a migration path
+
+This will probably cause a lot of confusion as native Keycloak organizations is released. We appreciate the patience and support that customers and users have shown us, and we hope to continue to support you with [great Keycloak extensions and tools](https://github.com/p2-inc).