docs: enhance error return values

ory · Oct 19, 2021 · 3799c24 · 3799c24
1 parent 9eafc10
commit 3799c24
Show file tree

Hide file tree

Showing 5 changed files with 51 additions and 10 deletions.
diff --git a/selfservice/flow/login/handler.go b/selfservice/flow/login/handler.go
@@ -307,6 +307,7 @@ type initializeSelfServiceLoginFlowForBrowsers struct {
 // - `has_session_already`: The user is already signed in.
 // - `aal_needs_session`: Multi-factor auth (e.g. 2fa) was requested but the user has no session yet.
 // - `csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
+// - `forbidden_return_to`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
 //
 // This endpoint is NOT INTENDED for clients that do not have a browser (Chrome, Firefox, ...) as cookies are needed.
 //
@@ -391,7 +392,6 @@ type getSelfServiceLoginFlow struct {
 //
 // - `has_session_already`: The user is already signed in.
 // - `self_service_flow_expired`: The flow is expired and you should request a new one.
-// - `forbidden_return_to`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
 //
 // More information can be found at [Ory Kratos User Login and User Registration Documentation](https://www.ory.sh/docs/next/kratos/self-service/flows/user-login-user-registration).
 //
@@ -489,6 +489,13 @@ type submitSelfServiceLoginFlowBody struct{}
 //   - HTTP 302 redirect to a fresh login flow if the original flow expired with the appropriate error messages set;
 //   - HTTP 400 on form validation errors.
 //
+// If this endpoint is called with `Accept: application/json` in the header, the response contains the flow without a redirect. In the
+// case of an error, the `error.id` of the JSON response body can be one of:
+//
+// - `has_session_already`: The user is already signed in.
+// - `csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
+// - `forbidden_return_to`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
+//
 // More information can be found at [Ory Kratos User Login and User Registration Documentation](https://www.ory.sh/docs/next/kratos/self-service/flows/user-login-user-registration).
 //
 //     Schemes: http, https

diff --git a/selfservice/flow/registration/handler.go b/selfservice/flow/registration/handler.go
@@ -199,6 +199,7 @@ type initializeSelfServiceRegistrationFlowForBrowsers struct {
 //
 // - `has_session_already`: The user is already signed in.
 // - `csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
+// - `forbidden_return_to`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
 //
 // If this endpoint is called via an AJAX request, the response contains the registration flow without a redirect.
 //
@@ -279,6 +280,11 @@ type getSelfServiceRegistrationFlow struct {
 //	})
 //	```
 //
+// This request may fail due to several reasons. The `error.id` can be one of:
+//
+// - `has_session_already`: The user is already signed in.
+// - `self_service_flow_expired`: The flow is expired and you should request a new one.
+//
 // More information can be found at [Ory Kratos User Login and User Registration Documentation](https://www.ory.sh/docs/next/kratos/self-service/flows/user-login-user-registration).
 //
 //     Produces:
@@ -365,6 +371,13 @@ type submitSelfServiceRegistrationFlowBody struct{}
 //   - HTTP 302 redirect to a fresh login flow if the original flow expired with the appropriate error messages set;
 //   - HTTP 400 on form validation errors.
 //
+// If this endpoint is called with `Accept: application/json` in the header, the response contains the flow without a redirect. In the
+// case of an error, the `error.id` of the JSON response body can be one of:
+//
+// - `has_session_already`: The user is already signed in.
+// - `csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
+// - `forbidden_return_to`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
+//
 // More information can be found at [Ory Kratos User Login and User Registration Documentation](https://www.ory.sh/docs/next/kratos/self-service/flows/user-login-user-registration).
 //
 //     Schemes: http, https

diff --git a/selfservice/flow/settings/error.go b/selfservice/flow/settings/error.go
@@ -51,7 +51,16 @@ type (
 //
 // swagger:model needsPrivilegedSessionError
 type FlowNeedsReAuth struct {
-	*herodot.DefaultError
+	*herodot.DefaultError `json:"error"`
+
+	// Points to where to redirect the user to next.
+	//
+	// required: true
+	RedirectBrowserTo string `json:"redirect_browser_to"`
+}
+
+func (e *FlowNeedsReAuth) EnhanceJSONError() interface{} {
+	return e
 }
 
 func NewFlowNeedsReAuth() *FlowNeedsReAuth {
@@ -68,17 +77,19 @@ func (s *ErrorHandler) reauthenticate(
 	w http.ResponseWriter,
 	r *http.Request,
 	f *Flow,
-	err error,
+	err *FlowNeedsReAuth,
 ) {
+	returnTo := urlx.CopyWithQuery(urlx.AppendPaths(s.d.Config(r.Context()).SelfPublicURL(r), r.URL.Path), r.URL.Query())
+	redirectTo := urlx.AppendPaths(urlx.CopyWithQuery(s.d.Config(r.Context()).SelfPublicURL(r),
+		url.Values{"refresh": {"true"}, "return_to": {returnTo.String()}}),
+		login.RouteInitBrowserFlow).String()
+	err.RedirectBrowserTo = redirectTo
 	if f.Type == flow.TypeAPI || x.IsJSONRequest(r) {
 		s.d.Writer().WriteError(w, r, err)
 		return
 	}
 
-	returnTo := urlx.CopyWithQuery(urlx.AppendPaths(s.d.Config(r.Context()).SelfPublicURL(r), r.URL.Path), r.URL.Query())
-	http.Redirect(w, r, urlx.AppendPaths(urlx.CopyWithQuery(s.d.Config(r.Context()).SelfPublicURL(r),
-		url.Values{"refresh": {"true"}, "return_to": {returnTo.String()}}),
-		login.RouteInitBrowserFlow).String(), http.StatusSeeOther)
+	http.Redirect(w, r, redirectTo, http.StatusSeeOther)
 }
 
 func (s *ErrorHandler) PrepareReplacementForExpiredFlow(w http.ResponseWriter, r *http.Request, f *Flow, id *identity.Identity, err error) (*flow.ExpiredError, error) {
@@ -167,7 +178,7 @@ func (s *ErrorHandler) WriteFlowError(
 	}
 
 	if e := new(FlowNeedsReAuth); errors.As(err, &e) {
-		s.reauthenticate(w, r, f, err)
+		s.reauthenticate(w, r, f, e)
 		return
 	}
 

diff --git a/selfservice/flow/settings/flow.go b/selfservice/flow/settings/flow.go
@@ -7,6 +7,8 @@ import (
 	"net/url"
 	"time"
 
+	"github.com/ory/kratos/text"
+
 	"github.com/tidwall/gjson"
 
 	"github.com/ory/kratos/driver/config"
@@ -177,7 +179,7 @@ func (f *Flow) Valid(s *session.Session) error {
 	}
 
 	if f.IdentityID != s.Identity.ID {
-		return errors.WithStack(herodot.ErrBadRequest.WithReasonf(
+		return errors.WithStack(herodot.ErrBadRequest.WithID(text.ErrIDInitiatedBySomeoneElse).WithReasonf(
 			"You must restart the flow because the resumable session was initiated by another person."))
 	}
 

diff --git a/selfservice/flow/settings/handler.go b/selfservice/flow/settings/handler.go
@@ -5,6 +5,8 @@ import (
 	"net/url"
 	"time"
 
+	"github.com/ory/kratos/text"
+
 	"github.com/ory/kratos/selfservice/flow/login"
 
 	"github.com/ory/kratos/ui/node"
@@ -242,6 +244,7 @@ type initializeSelfServiceSettingsFlowForBrowsers struct {
 //
 // - `csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
 // - `no_active_session`: No Ory Session was found - sign in a user first.
+// - `forbidden_return_to`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
 //
 // This endpoint is NOT INTENDED for clients that do not have a browser (Chrome, Firefox, ...) as cookies are needed.
 //
@@ -337,6 +340,8 @@ type getSelfServiceSettingsFlow struct {
 //
 // - `csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
 // - `no_active_session`: No Ory Session was found - sign in a user first.
+// - `intended_for_someone_else`: The flow was interrupted with `needs_privileged_session` but apparently some other
+//		identity logged in instead.
 //
 // More information can be found at [Ory Kratos User Settings & Profile Management Documentation](../self-service/flows/user-settings).
 //
@@ -378,7 +383,7 @@ func (h *Handler) fetchFlow(w http.ResponseWriter, r *http.Request) error {
 	}
 
 	if pr.IdentityID != sess.Identity.ID {
-		return errors.WithStack(herodot.ErrForbidden.WithReasonf("The request was made for another identity and has been blocked for security reasons."))
+		return errors.WithStack(herodot.ErrForbidden.WithID(text.ErrIDInitiatedBySomeoneElse).WithReasonf("The request was made for another identity and has been blocked for security reasons."))
 	}
 
 	if err := h.d.SessionManager().DoesSessionSatisfy(r, sess, h.d.Config(r.Context()).SelfServiceSettingsRequiredAAL()); err != nil {
@@ -467,6 +472,9 @@ type submitSelfServiceSettingsFlowBody struct{}
 //		or initiate a refresh login flow otherwise.
 // - `csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
 // - `no_active_session`: No Ory Session was found - sign in a user first.
+// - `intended_for_someone_else`: The flow was interrupted with `needs_privileged_session` but apparently some other
+//		identity logged in instead.
+// - `forbidden_return_to`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
 //
 // More information can be found at [Ory Kratos User Settings & Profile Management Documentation](../self-service/flows/user-settings).
 //