snapshot of https://github.com/ory/keto.git (master, 2026-09-16; blobs > 131072B omitted)

UPGRADE.md

@@ -0,0 +1,222 @@
+# Upgrading
+
+The intent of this document is to make migration of breaking changes as easy as
+possible. Please note that not all breaking changes might be included here.
+Please check the [CHANGELOG.md](./CHANGELOG.md) for a full list of changes
+before finalizing the upgrade process.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [0.4.0](#040)
+- [0.3.0-sandbox](#030-sandbox)
+  - [Configuration](#configuration)
+  - [ORY Access Control Policies Allowed Endpoint](#ory-access-control-policies-allowed-endpoint)
+  - [SDK](#sdk)
+- [0.2.0-sandbox](#020-sandbox)
+  - [Conceptual changes](#conceptual-changes)
+    - [Deprecated](#deprecated)
+    - [Changes](#changes)
+    - [Additions](#additions)
+    - [Untouched](#untouched)
+  - [API Changes](#api-changes)
+    - [Renamed Endpoints](#renamed-endpoints)
+    - [Reworked Endpoints](#reworked-endpoints)
+    - [New Endpoints](#new-endpoints)
+  - [Migration](#migration)
+    - [SQL](#sql)
+- [0.0.1](#001)
+  - [CORS is disabled by default](#cors-is-disabled-by-default)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 0.4.0-sandbox
+
+This release focuses on a rework of the SDK pipeline. First of all, we have
+introduced new SDKs for all popular programming languages and published them on
+their respective package repositories:
+
+- [Python](https://pypi.org/project/ory-keto-client/)
+- [PHP](https://packagist.org/packages/ory/keto-client)
+- [Go](https://github.com/ory/keto-client-go)
+- [NodeJS](https://www.npmjs.com/package/@oryd/keto-client) (with TypeScript)
+- [Java](https://search.maven.org/artifact/sh.ory.keto/keto-client)
+- [Ruby](https://rubygems.org/gems/ory-keto-client)
+
+The SDKs hosted in this repository (under ./sdk/...) have been completely
+removed. Please use only the SDKs from the above sources from now on as it will
+also remove several issues that were caused by the previous SDK pipeline.
+
+Unfortunately, there were breaking changes introduced by the new SDK generation:
+
+- Several structs and fields have been renamed in the Go SDK. However, nothing
+  else changed so upgrading should be a matter of half an hour if you made
+  extensive use of the SDK, or several minutes if just one or two methods are
+  being used.
+- All other SDKs changed to `openapi-generator`, which is a better maintained
+  generator that creates better code than the one previously used. This
+  manifests in TypeScript definitions for the NodeJS SDK and several other
+  goodies. We do not have a proper migration path for those, unfortunately.
+
+If you have issues with upgrading the SDK, please let us know in an issue on
+this repository!
+
+## 0.3.0-sandbox
+
+### Configuration
+
+The configuration management was updated and now allows configuration via a
+config file. Environment variables can still be used to configure ORY Keto but
+have been updated. However, old env vars still work but will yield a warning.
+
+An overview of an exemplary configuration file can be found in
+[./docs/config.yml](https://github.com/ory/hydra/blob/master/docs/config.yaml).
+
+### ORY Access Control Policies Allowed Endpoint
+
+Endpoint `/engines/acp/ory/{flavor}/allowed` now returns a 403 error when the
+request is disallowed.
+
+### SDK
+
+Generation of the Go SDK has moved from
+[`swagger-codegen`](https://github.com/swagger-api/swagger-codegen) to
+[`go-swagger`](https://github.com/go-swagger/go-swagger). If you wish to migrate
+your existing SDK integration please open an issue.
+
+## 0.2.0-sandbox
+
+ORY Keto has been completely reworked. The major goals of this refactoring are:
+
+1. To allow easy extension of existing access control mechanisms.
+2. Improve stability and responsiveness.
+3. Support more than one access control mechanism. Future mechanisms include:
+   RBAC, ACL, AWS IAM Policies, ...
+
+We know that these changes seem massive. They are, but they will benefit the
+long-term use of this particular piece of software, and they will allow you to
+build better systems.
+
+If you relied on ORY Keto before this release and you are looking for a
+migration path, don't hesitate to ask in
+[Ory Community Chat](https://slack.ory.com/) or open a
+[GitHub issue](https://github.com/ory/keto/issues/new/). Feel free to do the
+same if you want the access control policy feature implemented in ORY Hydra
+before version `1.0.0`.
+
+### Conceptual changes
+
+#### Deprecated
+
+The following things have been completely deprecated:
+
+1. Authorizers,
+2. Previous storage mechanisms.
+
+#### Changes
+
+The following things have changed:
+
+1. ORY Keto no longer uses ORY Ladon as the engine but instead relies on the
+   [Open Policy Agent](http://openpolicyagent.org/). The concept of ORY Ladon
+   Access Policies are working exactly like before, the internal logic however
+   was rewritten in Rego.
+2. The "Warden" concept has been deprecated and replaced.
+3. The CLI commands have changed - apart from `serve`, `version`,
+   `migrate sql` - entirely.
+4. The API has changed (read the next section for information on this).
+5. Environment variables changed or have been removed.
+
+#### Additions
+
+The following things have been added:
+
+1. ORY (Ladon) Access Control Policies with `exact` string `matching-strategy`.
+2. ORY (Ladon) Access Control Policies with `glob` string `matching-strategy`.
+
+#### Untouched
+
+The following things remain conceptually untouched:
+
+1. ORY (Ladon) Access Control Policies with `regex` string `matching-strategy`.
+   This is the logic that ORY Ladon and previous versions of ORY Keto implement.
+
+### API Changes
+
+#### Renamed Endpoints
+
+- `GET,PUT,POST,DELETE /policies[/<id>]` moved to
+  `/engines/acp/ory/<matching-strategy>/policies[/<id>]`.
+  - `POST /policies` has been deprecated and merged with `PUT /policies/<id>`
+    which is now available at
+    `PUT /engines/acp/ory/<matching-strategy>/policies` and will upsert (insert
+    or update) the policy identified by the `id` field in the JSON payload.
+  - The request & response payloads **did not change** nor did any of the
+    concepts.
+- `GET,PUT,POST,DELETE /roles[/<id>]` moved to
+  `/engines/acp/ory/<matching-strategy>/roles[/<id>]`.
+  - `POST /roles` has been deprecated and merged with `PUT /roles/<id>` which is
+    now available at `PUT /engines/acp/ory/<matching-strategy>/policies` and
+    will upsert (insert or update) the role identified by the `id` field in the
+    JSON payload.
+  - The request & response payloads **did not change** nor did any of the
+    concepts.
+- `POST,GET /roles/<id>/members` move to
+  `/engines/acp/ory/<matching-strategy>/roles/<id>/members`.
+  - `POST /roles` has been moved to
+    `PUT /engines/acp/ory/<matching-strategy>/policies/<id>/members` and will
+    upsert (insert or update) the role identified by the `id` field in the URL
+    path.
+  - The request & response payloads **did not change** nor did any of the
+    concepts.
+
+#### Reworked Endpoints
+
+The Warden concept has been deprecated. Previously, it was possible to send
+credentials alongside requests for prior authentication. This concept interfered
+with the clear boundary ORY Keto is focusing on, which is permissioning
+concepts.
+
+The Warden API featured endpoints such as:
+
+- `/warden/oauth2/access-tokens/authorize`: Permformed OAuth 2.0 Token
+  Introspection on the `token` field, took the `sub` value of the introspection
+  and used that as input to ORY (Ladon) Access Control Policies.
+- `/warden/oauth2/clients/authorize`: Validated the HTTP Basic Authorization
+  Header using the OAuth 2.0 Client Credentials grant and took the `username`
+  value of the HTTP Basic Authorization Header and used that as input to ORY
+  (Ladon) Access Control Policies.
+
+These endpoints have been deprecated without replacement. Another endpoint was
+`/warden/subjects/authorize` which used the format
+`{ "subject": "peter", "action": "delete", "resource": "something:valuable" }`
+as syntax. This endpoint is available in the exact same format at
+`/engines/acp/ory/<matching-strategy>/allowed`.
+
+#### New Endpoints
+
+- `GET /version`: Returns the running software version.
+- `GET /health/ready`: Returns `{"status": "ok"}` with a 200 HTTP response if
+  the service is ready to accept connections and handle data.
+- `GET /health/alive`: Returns `{"status": "ok"}` with a 200 HTTP response if
+  the service is ready to accept connections.
+
+### Migration
+
+If you relied on ORY Keto before this release and you are looking for a
+migration path, don't hesitate to [contact us](mailto:hi@ory.com). We will help
+you migrate and improve this guide as we see more migration use cases.
+
+#### SQL
+
+The SQL schema changed completely and it is not possible to migrate from the
+previous version to this version with just using `keto migrate sql`. Please ask
+in [the forums](https://community.ory.sh/) or open a
+[GitHub issue](https://github.com/ory/keto/issues/new/) if this affects you.
+
+## 0.0.1
+
+### CORS is disabled by default
+
+A new environment variable `CORS_ENABLED` was introduced. It sets whether CORS
+is enabled ("true") or not ("false")". Default is disabled.