diff --git a/docs/hydra/login-consent-flow.md b/docs/hydra/login-consent-flow.md deleted file mode 100644 index 57633c971..000000000 --- a/docs/hydra/login-consent-flow.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -id: login-consent-flow -title: User Login and Consent flow -sidebar_label: Ory OAuth2 & OpenID Connect workflow ---- - -Ory OAuth2 & OpenID Connect uses a **User Login and Consent Flow** to include third-party user management (implemented by you) -into the OAuth 2.0 and OpenID Connect authorization flow. An incoming authorization request is redirected to: - -1. the **Login Provider**: authenticates the user by validating his or her credentials (login) -2. the **Consent Provider**: allows to select the OAuth 2.0 scopes that should be granted to the requesting application ("Do you - want to allow foobar-app access to all your personal messages and images?") - -You implement the Login and Consent providers in the technology stack of your choice. - -## The flow steps - -The flow itself works as follows: - -1. The OAuth 2.0 Client initiates an Authorize Code, Hybrid, or Implicit flow. The user's user agent is redirect to - `http://hydra/oauth2/auth?client_id=...&...`. -2. Ory OAuth2 & OpenID Connect, if unable to authenticate the user (= no session cookie exists), redirects the user's user agent - to the Login Provider URL. The application "sitting" at that URL is implemented by you and typically shows a login user - interface ("Please enter your username and password"). The URL the user is redirect to looks similar to - `http://login-service/login?login_challenge=1234...`. -3. The Login Provider, once the user has successfully logged in, tells Ory OAuth2 & OpenID Connect some information about who the - user is (for example the user's ID) and also that the login attempt was successful. This is done using a REST request which - includes another redirect URL along the lines of `http://hydra/oauth2/auth?client_id=...&...&login_verifier=4321`. -4. The user's user agent follows the redirect and lands back at Ory OAuth2 & OpenID Connect. Next, Ory OAuth2 & OpenID Connect - redirects the user's user agent to the Consent Provider, hosted at - for example - - `http://consent-service/consent?consent_challenge=4567...` -5. The Consent Provider shows a user interface which asks the user if they would like to grant the OAuth 2.0 Client the requested - permissions ("OAuth 2.0 Scope"). You've probably seen this screen around, which is usually something similar to: _"Would you - like to grant Facebook Image Backup access to all your private and public images?"_. -6. The Consent Provider makes another REST request to Ory OAuth2 & OpenID Connect to let it know which permissions the user - authorized, and if the user authorized the request at all. The user can usually choose to not grant an application any access - to his/her personal data. In the response of that REST request, a redirect URL is included along the lines of - `http://hydra/oauth2/auth?client_id=...&...&consent_verifier=7654...`. -7. The user's user agent follows that redirect. -8. Now, the user has successfully authenticated and authorized the application. Next, Ory OAuth2 & OpenID Connect will run some - checks and if everything works out, issue access, refresh, and ID tokens. - -This flow allows you to take full control of the behavior of your login system (for example 2FA, passwordless, ...) and consent -screen. A well-documented reference implementation for both the Login and -[Consent Provider is available on GitHub](https://github.com/ory/hydra-login-consent-node). - -### The flow from a user's point of view - - - -### The flow from a network perspective - -[![Ory OAuth2 & OpenID User Login and Consent Flow](https://mermaid.ink/img/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtXG4gICAgT0F1dGgyIENsaWVudC0-Pk9SWSBIeWRyYTogSW5pdGlhdGVzIE9BdXRoMiBBdXRob3JpemUgQ29kZSBvciBJbXBsaWNpdCBGbG93XG4gICAgT1JZIEh5ZHJhLS0-Pk9SWSBIeWRyYTogTm8gZW5kIHVzZXIgc2Vzc2lvbiBhdmFpbGFibGUgKG5vdCBhdXRoZW50aWNhdGVkKVxuICAgIE9SWSBIeWRyYS0-PkxvZ2luIFByb3ZpZGVyOiBSZWRpcmVjdHMgZW5kIHVzZXIgd2l0aCBsb2dpbiBjaGFsbGVuZ2VcbiAgICBMb2dpbiBQcm92aWRlci0tPk9SWSBIeWRyYTogRmV0Y2hlcyBsb2dpbiBpbmZvXG4gICAgTG9naW4gUHJvdmlkZXItLT4-TG9naW4gUHJvdmlkZXI6IEF1dGhlbnRpY2F0ZXMgdXNlciB3aXRoIGNyZWRlbnRpYWxzXG4gICAgTG9naW4gUHJvdmlkZXItLT5PUlkgSHlkcmE6IFRyYW5zbWl0cyBsb2dpbiBpbmZvIGFuZCByZWNlaXZlcyByZWRpcmVjdCB1cmwgd2l0aCBsb2dpbiB2ZXJpZmllclxuICAgIExvZ2luIFByb3ZpZGVyLT4-T1JZIEh5ZHJhOiBSZWRpcmVjdHMgZW5kIHVzZXIgdG8gcmVkaXJlY3QgdXJsIHdpdGggbG9naW4gdmVyaWZpZXJcbiAgICBPUlkgSHlkcmEtLT4-T1JZIEh5ZHJhOiBGaXJzdCB0aW1lIHRoYXQgY2xpZW50IGFza3MgdXNlciBmb3IgcGVybWlzc2lvbnNcbiAgICBPUlkgSHlkcmEtPj5Db25zZW50IFByb3ZpZGVyOiBSZWRpcmVjdHMgZW5kIHVzZXIgd2l0aCBjb25zZW50IGNoYWxsZW5nZVxuICAgIENvbnNlbnQgUHJvdmlkZXItLT5PUlkgSHlkcmE6IEZldGNoZXMgY29uc2VudCBpbmZvICh3aGljaCB1c2VyLCB3aGF0IGFwcCwgd2hhdCBzY29wZXMpXG4gICAgQ29uc2VudCBQcm92aWRlci0tPj5Db25zZW50IFByb3ZpZGVyOiBBc2tzIGZvciBlbmQgdXNlcidzIHBlcm1pc3Npb24gdG8gZ3JhbnQgYXBwbGljYXRpb24gYWNjZXNzXG4gICAgQ29uc2VudCBQcm92aWRlci0tPk9SWSBIeWRyYTogVHJhbnNtaXRzIGNvbnNlbnQgcmVzdWx0IGFuZCByZWNlaXZlcyByZWRpcmVjdCB1cmwgd2l0aCBjb25zZW50IHZlcmlmaWVyXG4gICAgQ29uc2VudCBQcm92aWRlci0-Pk9SWSBIeWRyYTogUmVkaXJlY3RzIHRvIHJlZGlyZWN0IHVybCB3aXRoIGNvbnNlbnQgdmVyaWZpZXJcbiAgICBPUlkgSHlkcmEtLT4-T1JZIEh5ZHJhOiBWZXJpZmllcyBncmFudFxuICAgIE9SWSBIeWRyYS0-Pk9BdXRoMiBDbGllbnQ6IFRyYW5zbWl0cyBhdXRob3JpemF0aW9uIGNvZGUvdG9rZW4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9fQ)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtXG4gICAgT0F1dGgyIENsaWVudC0-Pk9SWSBIeWRyYTogSW5pdGlhdGVzIE9BdXRoMiBBdXRob3JpemUgQ29kZSBvciBJbXBsaWNpdCBGbG93XG4gICAgT1JZIEh5ZHJhLS0-Pk9SWSBIeWRyYTogTm8gZW5kIHVzZXIgc2Vzc2lvbiBhdmFpbGFibGUgKG5vdCBhdXRoZW50aWNhdGVkKVxuICAgIE9SWSBIeWRyYS0-PkxvZ2luIFByb3ZpZGVyOiBSZWRpcmVjdHMgZW5kIHVzZXIgd2l0aCBsb2dpbiBjaGFsbGVuZ2VcbiAgICBMb2dpbiBQcm92aWRlci0tPk9SWSBIeWRyYTogRmV0Y2hlcyBsb2dpbiBpbmZvXG4gICAgTG9naW4gUHJvdmlkZXItLT4-TG9naW4gUHJvdmlkZXI6IEF1dGhlbnRpY2F0ZXMgdXNlciB3aXRoIGNyZWRlbnRpYWxzXG4gICAgTG9naW4gUHJvdmlkZXItLT5PUlkgSHlkcmE6IFRyYW5zbWl0cyBsb2dpbiBpbmZvIGFuZCByZWNlaXZlcyByZWRpcmVjdCB1cmwgd2l0aCBsb2dpbiB2ZXJpZmllclxuICAgIExvZ2luIFByb3ZpZGVyLT4-T1JZIEh5ZHJhOiBSZWRpcmVjdHMgZW5kIHVzZXIgdG8gcmVkaXJlY3QgdXJsIHdpdGggbG9naW4gdmVyaWZpZXJcbiAgICBPUlkgSHlkcmEtLT4-T1JZIEh5ZHJhOiBGaXJzdCB0aW1lIHRoYXQgY2xpZW50IGFza3MgdXNlciBmb3IgcGVybWlzc2lvbnNcbiAgICBPUlkgSHlkcmEtPj5Db25zZW50IFByb3ZpZGVyOiBSZWRpcmVjdHMgZW5kIHVzZXIgd2l0aCBjb25zZW50IGNoYWxsZW5nZVxuICAgIENvbnNlbnQgUHJvdmlkZXItLT5PUlkgSHlkcmE6IEZldGNoZXMgY29uc2VudCBpbmZvICh3aGljaCB1c2VyLCB3aGF0IGFwcCwgd2hhdCBzY29wZXMpXG4gICAgQ29uc2VudCBQcm92aWRlci0tPj5Db25zZW50IFByb3ZpZGVyOiBBc2tzIGZvciBlbmQgdXNlcidzIHBlcm1pc3Npb24gdG8gZ3JhbnQgYXBwbGljYXRpb24gYWNjZXNzXG4gICAgQ29uc2VudCBQcm92aWRlci0tPk9SWSBIeWRyYTogVHJhbnNtaXRzIGNvbnNlbnQgcmVzdWx0IGFuZCByZWNlaXZlcyByZWRpcmVjdCB1cmwgd2l0aCBjb25zZW50IHZlcmlmaWVyXG4gICAgQ29uc2VudCBQcm92aWRlci0-Pk9SWSBIeWRyYTogUmVkaXJlY3RzIHRvIHJlZGlyZWN0IHVybCB3aXRoIGNvbnNlbnQgdmVyaWZpZXJcbiAgICBPUlkgSHlkcmEtLT4-T1JZIEh5ZHJhOiBWZXJpZmllcyBncmFudFxuICAgIE9SWSBIeWRyYS0-Pk9BdXRoMiBDbGllbnQ6IFRyYW5zbWl0cyBhdXRob3JpemF0aW9uIGNvZGUvdG9rZW4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9fQ) diff --git a/docs/oauth2-oidc/custom-login-consent/flow.mdx b/docs/oauth2-oidc/custom-login-consent/flow.mdx index ade1a8b62..c76560e04 100644 --- a/docs/oauth2-oidc/custom-login-consent/flow.mdx +++ b/docs/oauth2-oidc/custom-login-consent/flow.mdx @@ -220,6 +220,34 @@ The response contains information about the consent request. The body contains a interface must be shown. If skip is `true`, you shouldn't show the user interface but instead just accept or reject the consent request. +## Flow steps + +1. The OAuth 2.0 Client initiates an Authorize Code, Hybrid, or Implicit flow. The user's user agent is redirect to + `https://{project-slug}.projects.oryapis.com/oauth2/auth?client_id=...&...`. +2. Ory OAuth2, if unable to authenticate the user (= no session cookie exists), redirects the user's user agent to the Login + Provider URL. The application "sitting" at that URL is implemented by you and typically shows a login user interface ("Please + enter your username and password"). The URL the user is redirect to looks like + `https://example.org/oauth2-screens/login?login_challenge=1234...`. +3. The Login Provider, once the user has logged in, tells Ory OAuth2 some information about who the user is (for example the + user's ID) and also that the login attempt was successful. This is done using a REST request which includes another redirect + URL like `https://{project-slug}.projects.oryapis.com/oauth2/auth?client_id=...&...&login_verifier=4321`. +4. The user's user agent follows the redirect and lands back at Ory OAuth2. Next, Ory OAuth2 redirects the user's user agent to + the Consent Provider, hosted at - for example - `https://example.org/oauth2-screens/consent?consent_challenge=4567...` +5. The Consent Provider shows a user interface which asks the user if they would like to grant the OAuth 2.0 Client the requested + permissions ("OAuth 2.0 Scope"). You've probably seen this screen around, which is something like: _"Would you like to grant + Facebook Image Backup access to all your private and public images?"_. +6. The Consent Provider makes another REST request to Ory OAuth2 to let it know which permissions the user authorized, and if the + user authorized the request at all. The user can choose to not grant an application any access to his/her personal data. In the + response of that REST request, a redirect URL is included like + `https://{project-slug}.projects.oryapis.com/oauth2/auth?client_id=...&...&consent_verifier=7654...`. +7. The user's user agent follows that redirect. +8. Now, the user has authenticated and authorized the application. Next, Ory OAuth2 will run checks and if everything works out, + issue access, refresh, and ID tokens. + +This flow allows you to take full control of the behavior of your login system, authentication methods, and consent screen. A +well-documented reference implementation for both the Login and Consent Provider is available +[on GitHub](https://github.com/ory/hydra-login-consent-node). + ## Sequence diagram ```mdx-code-block diff --git a/vercel.json b/vercel.json index 415963883..27bcfe168 100644 --- a/vercel.json +++ b/vercel.json @@ -1044,6 +1044,11 @@ "destination": "/docs/oauth2-oidc/custom-login-consent/flow", "permanent": false }, + { + "source": "/docs/hydra/login-consent-flow", + "destination": "/docs/oauth2-oidc/custom-login-consent/flow", + "permanent": false + }, { "source": "/docs/hydra/concepts/logout", "destination": "/docs/oauth2-oidc/oidc-logout",