cmd: Fix 2-port tests and improve upgrade guide

Signed-off-by: arekkas <[email protected]>

.circleci/config.yml

@@ -40,7 +40,7 @@ jobs:
       - run: go test -race -short $(go list ./... | grep -v cmd)
       - run: ./scripts/test-e2e-jwt.sh
       - run: ./scripts/test-e2e-opaque.sh
-      - run: ./scripts/test-plugin.sh
+      - run: ./scripts/test-e2e-plugin.sh
       - run: test -z "$CIRCLE_PR_NUMBER" && goveralls -service=circle-ci -coverprofile=coverage.txt -repotoken=$COVERALLS_REPO_TOKEN || echo "forks are not allowed to push to coveralls"
 
   swagger:

UPGRADE.md

@@ -10,6 +10,10 @@ before finalizing the upgrade process.
 
 - [1.0.0-beta.8](#100-beta8)
   - [Schema Changes](#schema-changes)
+  - [Split of Public and Administrative Endpoints](#split-of-public-and-administrative-endpoints)
+  - [`hydra serve` is now `hydra serve all`](#hydra-serve-is-now-hydra-serve-all)
+  - [Environment variable `HYDRA_URL` now is `HYDRA_ADMIN_URL` for admin commands](#environment-variable-hydra_url-now-is-hydra_admin_url-for-admin-commands)
+  - [OAuth 2.0 Token Introspection](#oauth-20-token-introspection)
   - [OAuth 2.0 Client flag `public` has been removed](#oauth-20-client-flag-public-has-been-removed)
 - [1.0.0-beta.7](#100-beta7)
   - [Regenerated OpenID Connect ID Token cryptographic keys](#regenerated-openid-connect-id-token-cryptographic-keys)
@@ -101,14 +105,63 @@ before finalizing the upgrade process.
 This patch introduces some minor database schema changes. Before you apply it, you must run `hydra migrate sql` against
 your database.
 
-### Subcommands `admin`, `public`, `all` have been added to `hydra serve`
+### Split of Public and Administrative Endpoints
 
-With this patch, ORY Hydra exposes two ports:
+Previously, all endpoints were exposed at one port. Since access control was removed with version 1.0.0, administrative
+endpoints (JWKs management, OAuth 2.0 Client Management, Login & Consent Management) were exposed and had to be secured
+with sophisticated set ups using, for example, an API gateway to control which endpoints can be accessed by whom.
 
-- Public API (default port 4444) handles requests coming from the public internet, like OAuth 2.0 Authorization
-and Token requests, OpenID Connect UserInfo, OAuth 2.0 Token Revokation, and OpenID Connect Discovery.
-- Administrative API (default port 4445) handles administrative requests like managing OAuth 2.0 Clients,
-JSON Web Keys, login and consent sessions, and others.
+This version introduces a new port (default `:4445`, configurable using environment variables `ADMIN_PORT` and
+`ADMIN_POST`) which is serves all administrative APIs:
+
+* All `/clients` endpoints.
+* All `/jwks` endpoints.
+* All `/health`, `/metrics`, `/version` endpoints.
+* All `/oauth2/auth/requests` endpoints.
+* Endpoint `/oauth2/introspect`.
+* Endpoint `/oauth2/flush`.
+
+The second port exposes API endpoints generally available to the public (default `:4444`, configurable using environment
+variables `PUBLIC_PORT` and `PUBLIC_HOST`):
+
+* `./well-known/jwks.json`
+* `./well-known/openid-configuration`
+* `/oauth2/auth`
+* `/oauth2/token`
+* `/oauth2/revoke`
+* `/oauth2/fallbacks/consent`
+* `/oauth2/fallbacks/error`
+* `/userinfo`
+
+The simplest way to starting both ports is to run `hydra serve`. This will start a process which listens on both ports
+and exposes their respective features. All settings (cors, database, tls, ...) will be shared by both listeners.
+
+To configure each listener differently - for example setting CORS for public but not privileged APIs - you can run
+`hydra serve public` and `hydra serve admin` with different settings. Be aware that this will not work with `DATABASE=memory`
+and that both services must use the same secrets.
+
+### `hydra serve` is now `hydra serve all`
+
+To reflect the changes of public and administrative ports, command `hydra serve` is now `hydra serve all`.
+
+### Environment variable `HYDRA_URL` now is `HYDRA_ADMIN_URL` for admin commands
+
+CLI Commands like `hydra clients ...`, `hydra keys ...`, `hydra token flush`, `hydra token introspect` no longer use
+environment variable `HYDRA_URL` as default for `--endpoint` but instead `HYDRA_ADMIN_URL`.
+
+### OAuth 2.0 Token Introspection
+
+Previously, OAuth 2.0 Token Introspection was protected with HTTP Basic Authorization (a valid OAuth 2.0 Client with
+Client ID and Client Secret was needed) or HTTP Bearer Authorization (a valid OAuth 2.0 Access Token was needed).
+
+As OAuth 2.0 Token Introspection is generally an internal-facing endpoint used by resource servers to validate
+OAuth 2.0 Access Tokens, this endpoint has moved to the privileged port. The specification does not implore which
+authorization scheme must be used - it only shows that HTTP Basic/Bearer Authorization may be used. By exposing this
+endpoint to the privileged port a strong authorization scheme is implemented and no further authorization is needed.
+Thus, access control was stripped from this endpoint, making integration with other API gateways easier.
+
+You may still choose to export this endpoint to the public internet and implement any access control mechanism you find
+appropriate.
 
 ### OAuth 2.0 Client flag `public` has been removed
 

cmd/clients.go

@@ -38,7 +38,7 @@ func init() {
 	//clientsCmd.PersistentFlags().Bool("dry", false, "do not execute the command but show the corresponding curl command instead")
 	clientsCmd.PersistentFlags().Bool("fake-tls-termination", false, `Fake tls termination by adding "X-Forwarded-Proto: https" to http headers`)
 	clientsCmd.PersistentFlags().String("access-token", os.Getenv("OAUTH2_ACCESS_TOKEN"), "Set an access token to be used in the Authorization header, defaults to environment variable ACCESS_TOKEN")
-	clientsCmd.PersistentFlags().String("endpoint", os.Getenv("HYDRA_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_URL")
+	clientsCmd.PersistentFlags().String("endpoint", os.Getenv("HYDRA_ADMIN_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_ADMIN_URL")
 
 	// Here you will define your flags and configuration settings.
 

cmd/keys.go

@@ -37,7 +37,7 @@ func init() {
 	//keysCmd.PersistentFlags().Bool("dry", false, "do not execute the command but show the corresponding curl command instead")
 	keysCmd.PersistentFlags().Bool("fake-tls-termination", false, `fake tls termination by adding "X-Forwarded-Proto: https" to http headers`)
 	keysCmd.PersistentFlags().String("access-token", os.Getenv("OAUTH2_ACCESS_TOKEN"), "Set an access token to be used in the Authorization header, defaults to environment variable ACCESS_TOKEN")
-	keysCmd.PersistentFlags().String("endpoint", os.Getenv("HYDRA_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_URL")
+	keysCmd.PersistentFlags().String("endpoint", os.Getenv("HYDRA_ADMIN_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_ADMIN_URL")
 
 	// Here you will define your flags and configuration settings.
 

cmd/server/handler_test.go

@@ -35,5 +35,5 @@ func TestStart(t *testing.T) {
 			OAuth2AccessTokenStrategy: "opaque",
 		},
 	}
-	h.registerRoutes(router,router)
+	h.registerRoutes(router, router)
 }

cmd/token_flush.go

@@ -39,5 +39,5 @@ func init() {
 
 	tokenFlushCmd.Flags().Duration("min-age", time.Duration(0), "Skip removing tokens which do not satisfy the minimum age (1s, 1m, 1h, 1d)")
 	tokenFlushCmd.Flags().String("access-token", os.Getenv("OAUTH2_ACCESS_TOKEN"), "Set an access token to be used in the Authorization header, defaults to environment variable ACCESS_TOKEN")
-	tokenFlushCmd.Flags().String("endpoint", os.Getenv("HYDRA_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_URL")
+	tokenFlushCmd.Flags().String("endpoint", os.Getenv("HYDRA_ADMIN_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_ADMIN_URL")
 }

cmd/token_introspect.go

@@ -36,7 +36,7 @@ var tokenIntrospectCmd = &cobra.Command{
 func init() {
 	tokenCmd.AddCommand(tokenIntrospectCmd)
 	tokenIntrospectCmd.Flags().StringSlice("scope", []string{}, "Additionally check if scope was granted")
-	tokenIntrospectCmd.Flags().String("endpoint", os.Getenv("HYDRA_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_URL")
+	tokenIntrospectCmd.Flags().String("endpoint", os.Getenv("HYDRA_ADMIN_URL"), "Set the URL where ORY Hydra is hosted, defaults to environment variable HYDRA_ADMIN_URL")
 	tokenIntrospectCmd.Flags().String("client-id", os.Getenv("OAUTH2_CLIENT_ID"), "Use the provided OAuth 2.0 Client ID, defaults to environment variable OAUTH2_CLIENT_ID")
 	tokenIntrospectCmd.Flags().String("client-secret", os.Getenv("OAUTH2_CLIENT_SECRET"), "Use the provided OAuth 2.0 Client Secret, defaults to environment variable OAUTH2_CLIENT_SECRET")
 }

docker-compose-twoc.yml

@@ -0,0 +1,107 @@
+###########################################################################
+#######             FOR DEMONSTRATION PURPOSES ONLY                 #######
+###########################################################################
+#                                                                         #
+# If you have not yet read the tutorial, do so now:                       #
+#  https://ory-am.gitbooks.io/hydra/content/tutorial.html                 #
+#                                                                         #
+# This set up is only for demonstration purposes. The login               #
+# endpoint can only be used if you follow the steps in the tutorial.      #
+#                                                                         #
+###########################################################################
+
+version: '2'
+
+services:
+
+  hydra-migrate:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    links:
+      - postgresd:postgresd
+    environment:
+#      - LOG_LEVEL=debug
+      - DATABASE_URL=postgres://hydra:secret@postgresd:5432/hydra?sslmode=disable
+    command:
+      migrate sql -e
+    restart: on-failure
+
+  hydra-admin:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    links:
+      - postgresd:postgresd
+#     Uncomment the following line to use mysql instead.
+#      - mysqld:mysqld
+    depends_on:
+      - hydra-migrate
+    ports:
+      - "4445:4445"
+    command:
+      serve admin --dangerous-force-http
+    environment:
+#      - LOG_LEVEL=debug
+      - OAUTH2_ISSUER_URL=http://localhost:4444
+      - OAUTH2_CONSENT_URL=http://localhost:3000/consent
+      - OAUTH2_LOGIN_URL=http://localhost:3000/login
+      - DATABASE_URL=postgres://hydra:secret@postgresd:5432/hydra?sslmode=disable
+#     Uncomment the following line to use mysql instead.
+#      - DATABASE_URL=mysql://root:secret@tcp(mysqld:3306)/mysql?parseTime=true
+      - SYSTEM_SECRET=youReallyNeedToChangeThis
+      - OAUTH2_SHARE_ERROR_DEBUG=1
+#      - OAUTH2_ACCESS_TOKEN_STRATEGY=jwt
+    restart: unless-stopped
+
+  hydra:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    links:
+      - postgresd:postgresd
+#     Uncomment the following line to use mysql instead.
+#      - mysqld:mysqld
+    depends_on:
+      - hydra-migrate
+    ports:
+      - "4444:4444"
+    command:
+      serve public --dangerous-force-http
+    environment:
+#      - LOG_LEVEL=debug
+      - OAUTH2_ISSUER_URL=http://localhost:4444
+      - OAUTH2_CONSENT_URL=http://localhost:3000/consent
+      - OAUTH2_LOGIN_URL=http://localhost:3000/login
+      - DATABASE_URL=postgres://hydra:secret@postgresd:5432/hydra?sslmode=disable
+#     Uncomment the following line to use mysql instead.
+#      - DATABASE_URL=mysql://root:secret@tcp(mysqld:3306)/mysql?parseTime=true
+      - SYSTEM_SECRET=youReallyNeedToChangeThis
+      - OAUTH2_SHARE_ERROR_DEBUG=1
+#      - OAUTH2_ACCESS_TOKEN_STRATEGY=jwt
+    restart: unless-stopped
+
+  consent:
+    environment:
+      - HYDRA_URL=http://hydra-admin:4445
+    image: oryd/hydra-login-consent-node:v1.0.0-beta.7
+    links:
+      - hydra-admin
+    ports:
+      - "3000:3000"
+    restart: unless-stopped
+
+  postgresd:
+    image: postgres:9.6
+    ports:
+      - "5432:5432"
+    environment:
+      - POSTGRES_USER=hydra
+      - POSTGRES_PASSWORD=secret
+      - POSTGRES_DB=hydra
+
+#  Uncomment the following section to use mysql instead.
+#  mysqld:
+#    image: mysql:5.7
+#    environment:
+#      - MYSQL_ROOT_PASSWORD=secret

docker-compose.yml

@@ -42,6 +42,8 @@ services:
       - "4444:4444"
       # Admin port
       - "4445:4445"
+      # Port for hydra token user
+      - "5555:5555"
     command:
       serve all --dangerous-force-http
     environment:
@@ -59,8 +61,8 @@ services:
 
   consent:
     environment:
-      - HYDRA_URL=http://hydra:4444
-    image: oryd/hydra-login-consent-node:v1.0.0-beta.1
+      - HYDRA_URL=http://hydra:4445
+    image: oryd/hydra-login-consent-node:v1.0.0-beta.7
     links:
       - hydra
     ports: