refactor: all admin endpoints are now exposed under /admin/ on the …

…admin port BREAKING CHANGE: All endpoints at the Admin API are now exposed at `/admin/`. For example, endpoint `https://kratos:4434/identities` is now exposed at `https://kratos:4434/admin/identities`. This change makes it easier to configure reverse proxies and API Gateways. Additionally, it introduces 1:1 compatibility between Ory Cloud's APIs and self-hosted Ory Kratos. Please note that nothing has changed in terms of the port. To make the migration less painful, we have set up redirects from the old endpoints to the new `/admin` endpoints, so your APIs, SDKs, and clients should continue working as they were working before. This change is marked as a breaking change as it touches many endpoints and might be confusing when encountering the redirect for the first time.
ory · Mar 9, 2022 · 8acb4cf · 8acb4cf
1 parent c7682a8
commit 8acb4cf
Show file tree

Hide file tree

Showing 33 changed files with 590 additions and 312 deletions.
diff --git a/cmd/daemon/serve.go b/cmd/daemon/serve.go
@@ -5,6 +5,8 @@ import (
 	"net/http"
 	"sync"
 
+	"github.com/ory/kratos/schema"
+
 	"github.com/ory/kratos/selfservice/flow/recovery"
 
 	"github.com/ory/x/reqlog"
@@ -162,6 +164,7 @@ func ServeAdmin(r driver.Registry, wg *sync.WaitGroup, cmd *cobra.Command, args
 		adminLogger.ExcludePaths(healthx.AliveCheckPath, healthx.ReadyCheckPath)
 	}
 	n.Use(adminLogger)
+	n.UseFunc(x.RedirectAdminMiddleware)
 	n.Use(x.HTTPLoaderContextMiddleware(r))
 	n.Use(sqa(ctx, cmd, r))
 	n.Use(r.PrometheusManager())
@@ -234,7 +237,9 @@ func sqa(ctx stdctx.Context, cmd *cobra.Command, d driver.Registry) *metricsx.Se
 				registration.RouteSubmitFlow,
 
 				session.RouteWhoami,
-				identity.RouteCollection,
+
+				x.AdminPrefix + "/" + schema.SchemasPath,
+				x.AdminPrefix + identity.RouteCollection,
 
 				settings.RouteInitBrowserFlow,
 				settings.RouteInitAPIFlow,

diff --git a/driver/config/handler.go b/driver/config/handler.go
@@ -9,7 +9,11 @@ import (
 	"github.com/knadh/koanf/parsers/json"
 )
 
-func NewConfigHashHandler(c Provider, router *httprouter.Router) {
+type router interface {
+	GET(path string, handle httprouter.Handle)
+}
+
+func NewConfigHashHandler(c Provider, router router) {
 	router.GET("/health/config", func(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 		bytes, _ := c.Config(r.Context()).Source().Marshal(json.Parser())
 		sum := sha256.Sum256(bytes)

diff --git a/driver/registry_default.go b/driver/registry_default.go
@@ -187,11 +187,11 @@ func (m *RegistryDefault) RegisterAdminRoutes(ctx context.Context, router *x.Rou
 	m.VerificationHandler().RegisterAdminRoutes(router)
 	m.AllVerificationStrategies().RegisterAdminRoutes(router)
 
-	m.HealthHandler(ctx).SetHealthRoutes(router.Router, true)
-	m.HealthHandler(ctx).SetVersionRoutes(router.Router)
-	m.MetricsHandler().SetRoutes(router.Router)
+	m.HealthHandler(ctx).SetHealthRoutes(router, true)
+	m.HealthHandler(ctx).SetVersionRoutes(router)
+	m.MetricsHandler().SetRoutes(router)
 
-	config.NewConfigHashHandler(m, router.Router)
+	config.NewConfigHashHandler(m, router)
 }
 
 func (m *RegistryDefault) RegisterRoutes(ctx context.Context, public *x.RouterPublic, admin *x.RouterAdmin) {

diff --git a/go.mod b/go.mod
@@ -76,7 +76,7 @@ require (
 	github.com/ory/kratos-client-go v0.6.3-alpha.1
 	github.com/ory/mail/v3 v3.0.0
 	github.com/ory/nosurf v1.2.7
-	github.com/ory/x v0.0.351
+	github.com/ory/x v0.0.353-0.20220307112550-60a38e67a6eb
 	github.com/phayes/freeport v0.0.0-20180830031419-95f893ade6f2
 	github.com/pkg/errors v0.9.1
 	github.com/pquerna/otp v1.3.0

diff --git a/go.sum b/go.sum
@@ -1806,8 +1806,8 @@ github.com/ory/x v0.0.205/go.mod h1:A1s4iwmFIppRXZLF3J9GGWeY/HpREVm0Dk5z/787iek=
 github.com/ory/x v0.0.250/go.mod h1:jUJaVptu+geeqlb9SyQCogTKj5ztSDIF6APkhbKtwLc=
 github.com/ory/x v0.0.272/go.mod h1:1TTPgJGQutrhI2OnwdrTIHE9ITSf4MpzXFzA/ncTGRc=
 github.com/ory/x v0.0.288/go.mod h1:APpShLyJcVzKw1kTgrHI+j/L9YM+8BRjHlcYObc7C1U=
-github.com/ory/x v0.0.351 h1:RkiK5MH7rCm461SmHvGJopHWGToTkGLaC8VOrTis6cM=
-github.com/ory/x v0.0.351/go.mod h1:zuNjBKtyxFpKnDG6q/1QP0pqQv840P/Dw5JbdY7lNTU=
+github.com/ory/x v0.0.353-0.20220307112550-60a38e67a6eb h1:+Ia9h/jNldl3jTMTWl0VOqk3v0URFsQyZjm0NMVDM2g=
+github.com/ory/x v0.0.353-0.20220307112550-60a38e67a6eb/go.mod h1:zuNjBKtyxFpKnDG6q/1QP0pqQv840P/Dw5JbdY7lNTU=
 github.com/otiai10/copy v1.2.0/go.mod h1:rrF5dJ5F0t/EWSYODDu4j9/vEeYHMkc8jt0zJChqQWw=
 github.com/otiai10/curr v0.0.0-20150429015615-9b4961190c95/go.mod h1:9qAhocn7zKJG+0mI8eUu6xqkFDYS2kb2saOteoSB3cE=
 github.com/otiai10/curr v1.0.0/go.mod h1:LskTG5wDwr8Rs+nNQ+1LlxRjAtTZZjtJW4rMXl6j4vs=

diff --git a/identity/handler.go b/identity/handler.go
@@ -55,12 +55,22 @@ func NewHandler(r handlerDependencies) *Handler {
 }
 
 func (h *Handler) RegisterPublicRoutes(public *x.RouterPublic) {
-	h.r.CSRFHandler().IgnoreGlobs(RouteCollection, RouteCollection+"/*")
+	h.r.CSRFHandler().IgnoreGlobs(
+		RouteCollection, RouteCollection+"/*",
+		x.AdminPrefix+RouteCollection, x.AdminPrefix+RouteCollection+"/*",
+	)
+
 	public.GET(RouteCollection, x.RedirectToAdminRoute(h.r))
 	public.GET(RouteItem, x.RedirectToAdminRoute(h.r))
 	public.DELETE(RouteItem, x.RedirectToAdminRoute(h.r))
 	public.POST(RouteCollection, x.RedirectToAdminRoute(h.r))
 	public.PUT(RouteItem, x.RedirectToAdminRoute(h.r))
+
+	public.GET(x.AdminPrefix+RouteCollection, x.RedirectToAdminRoute(h.r))
+	public.GET(x.AdminPrefix+RouteItem, x.RedirectToAdminRoute(h.r))
+	public.DELETE(x.AdminPrefix+RouteItem, x.RedirectToAdminRoute(h.r))
+	public.POST(x.AdminPrefix+RouteCollection, x.RedirectToAdminRoute(h.r))
+	public.PUT(x.AdminPrefix+RouteItem, x.RedirectToAdminRoute(h.r))
 }
 
 func (h *Handler) RegisterAdminRoutes(admin *x.RouterAdmin) {
@@ -83,7 +93,7 @@ type adminListIdentities struct {
 	x.PaginationParams
 }
 
-// swagger:route GET /identities v0alpha2 adminListIdentities
+// swagger:route GET /admin/identities v0alpha2 adminListIdentities
 //
 // List Identities
 //
@@ -139,7 +149,7 @@ type adminGetIdentity struct {
 	DeclassifyCredentials []string `json:"include_credential"`
 }
 
-// swagger:route GET /identities/{id} v0alpha2 adminGetIdentity
+// swagger:route GET /admin/identities/{id} v0alpha2 adminGetIdentity
 //
 // Get an Identity
 //
@@ -281,7 +291,7 @@ type AdminCreateIdentityImportCredentialsOidcProvider struct {
 	Provider string `json:"provider"`
 }
 
-// swagger:route POST /identities v0alpha2 adminCreateIdentity
+// swagger:route POST /admin/identities v0alpha2 adminCreateIdentity
 //
 // Create an Identity
 //
@@ -385,7 +395,7 @@ type AdminUpdateIdentityBody struct {
 	State State `json:"state"`
 }
 
-// swagger:route PUT /identities/{id} v0alpha2 adminUpdateIdentity
+// swagger:route PUT /admin/identities/{id} v0alpha2 adminUpdateIdentity
 //
 // Update an Identity
 //
@@ -466,7 +476,7 @@ type adminDeleteIdentity struct {
 	ID string `json:"id"`
 }
 
-// swagger:route DELETE /identities/{id} v0alpha2 adminDeleteIdentity
+// swagger:route DELETE /admin/identities/{id} v0alpha2 adminDeleteIdentity
 //
 // Delete an Identity
 //

diff --git a/identity/handler_test.go b/identity/handler_test.go
@@ -385,6 +385,7 @@ func TestHandler(t *testing.T) {
 					assert.Contains(t, res.Raw, "Internal Server Error", res.Raw)
 				})
 			}
+
 			e, _ := reg.Cipher().Encrypt(context.Background(), []byte("foo_token"))
 			id = createOidcIdentity(t, "[email protected]", e, "bar_token", "id_token", false)
 			for name, ts := range map[string]*httptest.Server{"public": publicTS, "admin": adminTS} {

diff --git a/internal/httpclient/README.md b/internal/httpclient/README.md
@@ -86,14 +86,14 @@ Class | Method | HTTP request | Description
 *MetadataApi* | [**GetVersion**](docs/MetadataApi.md#getversion) | **Get** /version | Return Running Software Version.
 *MetadataApi* | [**IsAlive**](docs/MetadataApi.md#isalive) | **Get** /health/alive | Check HTTP Server Status
 *MetadataApi* | [**IsReady**](docs/MetadataApi.md#isready) | **Get** /health/ready | Check HTTP Server and Database Status
-*V0alpha2Api* | [**AdminCreateIdentity**](docs/V0alpha2Api.md#admincreateidentity) | **Post** /identities | Create an Identity
-*V0alpha2Api* | [**AdminCreateSelfServiceRecoveryLink**](docs/V0alpha2Api.md#admincreateselfservicerecoverylink) | **Post** /recovery/link | Create a Recovery Link
-*V0alpha2Api* | [**AdminDeleteIdentity**](docs/V0alpha2Api.md#admindeleteidentity) | **Delete** /identities/{id} | Delete an Identity
-*V0alpha2Api* | [**AdminDeleteIdentitySessions**](docs/V0alpha2Api.md#admindeleteidentitysessions) | **Delete** /identities/{id}/sessions | Calling this endpoint irrecoverably and permanently deletes and invalidates all sessions that belong to the given Identity.
-*V0alpha2Api* | [**AdminGetIdentity**](docs/V0alpha2Api.md#admingetidentity) | **Get** /identities/{id} | Get an Identity
-*V0alpha2Api* | [**AdminListIdentities**](docs/V0alpha2Api.md#adminlistidentities) | **Get** /identities | List Identities
-*V0alpha2Api* | [**AdminListIdentitySessions**](docs/V0alpha2Api.md#adminlistidentitysessions) | **Get** /identities/{id}/sessions | This endpoint returns all sessions that belong to the given Identity.
-*V0alpha2Api* | [**AdminUpdateIdentity**](docs/V0alpha2Api.md#adminupdateidentity) | **Put** /identities/{id} | Update an Identity
+*V0alpha2Api* | [**AdminCreateIdentity**](docs/V0alpha2Api.md#admincreateidentity) | **Post** /admin/identities | Create an Identity
+*V0alpha2Api* | [**AdminCreateSelfServiceRecoveryLink**](docs/V0alpha2Api.md#admincreateselfservicerecoverylink) | **Post** /admin/recovery/link | Create a Recovery Link
+*V0alpha2Api* | [**AdminDeleteIdentity**](docs/V0alpha2Api.md#admindeleteidentity) | **Delete** /admin/identities/{id} | Delete an Identity
+*V0alpha2Api* | [**AdminDeleteIdentitySessions**](docs/V0alpha2Api.md#admindeleteidentitysessions) | **Delete** /admin/identities/{id}/sessions | Calling this endpoint irrecoverably and permanently deletes and invalidates all sessions that belong to the given Identity.
+*V0alpha2Api* | [**AdminGetIdentity**](docs/V0alpha2Api.md#admingetidentity) | **Get** /admin/identities/{id} | Get an Identity
+*V0alpha2Api* | [**AdminListIdentities**](docs/V0alpha2Api.md#adminlistidentities) | **Get** /admin/identities | List Identities
+*V0alpha2Api* | [**AdminListIdentitySessions**](docs/V0alpha2Api.md#adminlistidentitysessions) | **Get** /admin/identities/{id}/sessions | This endpoint returns all sessions that belong to the given Identity.
+*V0alpha2Api* | [**AdminUpdateIdentity**](docs/V0alpha2Api.md#adminupdateidentity) | **Put** /admin/identities/{id} | Update an Identity
 *V0alpha2Api* | [**CreateSelfServiceLogoutFlowUrlForBrowsers**](docs/V0alpha2Api.md#createselfservicelogoutflowurlforbrowsers) | **Get** /self-service/logout/browser | Create a Logout URL for Browsers
 *V0alpha2Api* | [**GetJsonSchema**](docs/V0alpha2Api.md#getjsonschema) | **Get** /schemas/{id} | 
 *V0alpha2Api* | [**GetSelfServiceError**](docs/V0alpha2Api.md#getselfserviceerror) | **Get** /self-service/errors | Get Self-Service Errors

diff --git a/internal/httpclient/api/openapi.yaml b/internal/httpclient/api/openapi.yaml
@@ -37,63 +37,7 @@ paths:
       summary: Get WebAuthn JavaScript
       tags:
       - v0alpha2
-  /health/alive:
-    get:
-      description: |-
-        This endpoint returns a HTTP 200 status code when Ory Kratos is accepting incoming
-        HTTP requests. This status does currently not include checks whether the database connection is working.
-
-        If the service supports TLS Edge Termination, this endpoint does not require the
-        `X-Forwarded-Proto` header to be set.
-
-        Be aware that if you are running multiple nodes of this service, the health status will never
-        refer to the cluster state, only to a single instance.
-      operationId: isAlive
-      responses:
-        "200":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/inline_response_200'
-          description: Ory Kratos is ready to accept connections.
-        "500":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/genericError'
-          description: genericError
-      summary: Check HTTP Server Status
-      tags:
-      - metadata
-  /health/ready:
-    get:
-      description: |-
-        This endpoint returns a HTTP 200 status code when Ory Kratos is up running and the environment dependencies (e.g.
-        the database) are responsive as well.
-
-        If the service supports TLS Edge Termination, this endpoint does not require the
-        `X-Forwarded-Proto` header to be set.
-
-        Be aware that if you are running multiple nodes of Ory Kratos, the health status will never
-        refer to the cluster state, only to a single instance.
-      operationId: isReady
-      responses:
-        "200":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/inline_response_200'
-          description: Ory Kratos is ready to accept requests.
-        "503":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/inline_response_503'
-          description: Ory Kratos is not yet ready to accept requests.
-      summary: Check HTTP Server and Database Status
-      tags:
-      - metadata
-  /identities:
+  /admin/identities:
     get:
       description: |-
         Lists all identities. Does not support search at the moment.
@@ -188,7 +132,7 @@ paths:
       summary: Create an Identity
       tags:
       - v0alpha2
-  /identities/{id}:
+  /admin/identities/{id}:
     delete:
       description: |-
         Calling this endpoint irrecoverably and permanently deletes the identity given its ID. This action can not be undone.
@@ -338,7 +282,7 @@ paths:
       summary: Update an Identity
       tags:
       - v0alpha2
-  /identities/{id}/sessions:
+  /admin/identities/{id}/sessions:
     delete:
       description: |-
         This endpoint is useful for:
@@ -474,7 +418,7 @@ paths:
       summary: This endpoint returns all sessions that belong to the given Identity.
       tags:
       - v0alpha2
-  /recovery/link:
+  /admin/recovery/link:
     post:
       description: |-
         This endpoint creates a recovery link which should be given to the user in order for them to recover
@@ -514,6 +458,62 @@ paths:
       summary: Create a Recovery Link
       tags:
       - v0alpha2
+  /health/alive:
+    get:
+      description: |-
+        This endpoint returns a HTTP 200 status code when Ory Kratos is accepting incoming
+        HTTP requests. This status does currently not include checks whether the database connection is working.
+
+        If the service supports TLS Edge Termination, this endpoint does not require the
+        `X-Forwarded-Proto` header to be set.
+
+        Be aware that if you are running multiple nodes of this service, the health status will never
+        refer to the cluster state, only to a single instance.
+      operationId: isAlive
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/inline_response_200'
+          description: Ory Kratos is ready to accept connections.
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/genericError'
+          description: genericError
+      summary: Check HTTP Server Status
+      tags:
+      - metadata
+  /health/ready:
+    get:
+      description: |-
+        This endpoint returns a HTTP 200 status code when Ory Kratos is up running and the environment dependencies (e.g.
+        the database) are responsive as well.
+
+        If the service supports TLS Edge Termination, this endpoint does not require the
+        `X-Forwarded-Proto` header to be set.
+
+        Be aware that if you are running multiple nodes of Ory Kratos, the health status will never
+        refer to the cluster state, only to a single instance.
+      operationId: isReady
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/inline_response_200'
+          description: Ory Kratos is ready to accept requests.
+        "503":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/inline_response_503'
+          description: Ory Kratos is not yet ready to accept requests.
+      summary: Check HTTP Server and Database Status
+      tags:
+      - metadata
   /schemas:
     get:
       description: Get all Identity Schemas