From 7d0e47058cd6dca1763f01e45ed46cee49321240 Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Thu, 3 Sep 2020 16:27:25 +0200 Subject: [PATCH] docs: bring oidc docs up to date --- ...n-with-github-google-facebook-linkedin.mdx | 6 +- .../openid-connect-social-sign-in-oauth2.mdx | 313 +++++++++--------- .../username-email-password.mdx | 71 +++- 3 files changed, 208 insertions(+), 182 deletions(-) diff --git a/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx b/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx index 7f7f1c03de8..4583af2c2fa 100644 --- a/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx +++ b/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx @@ -51,13 +51,13 @@ To set up "Sign in with GitHub" you must create a Set the "Authorization callback URL" to: ``` -http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/strategies/oidc/callback/github +http://127.0.0.1:4433/self-service/methods/oidc/callback/github ``` The pattern of this URL is: ``` -http(s)://:/self-service/browser/flows/strategies/oidc/callback/ +http(s)://://self-service/methods/oidc/callback/ ``` The provider ID must point to the provider's ID set in the ORY Kratos @@ -140,7 +140,7 @@ To set up "Sign in with Microsoft" you must first Select "Web" as the "Redirect URI" type, and set the URI to: ``` -http(s)://:/self-service/browser/flows/strategies/oidc/callback/ +http(s)://://self-service/methods/oidc/callback/ ``` After the "App Registration" is created, make note of the `Application ID` and diff --git a/docs/docs/self-service/flows/user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx b/docs/docs/self-service/flows/user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx index af81cd4c71d..6f8522bf448 100644 --- a/docs/docs/self-service/flows/user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx +++ b/docs/docs/self-service/flows/user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx @@ -84,74 +84,56 @@ selfservice: Redirecting the browser to the [Self-Service Login and Registration Endpoint](../user-login-user-registration.mdx#user-login-and-user-registration-process-sequence) -initiates the flow. If the `oidc` method is enabled and at least one provider -is configued, the Registration Request Response Payload will include an `oidc` +initiates the flow: + +```shell script +$ curl -s -D - -X GET --cookie cookie.txt --cookie-jar cookie.txt \ + http://127.0.0.1:4433/self-service/registration/browser + +HTTP/1.1 302 Found +Cache-Control: 0 +Content-Type: text/html; charset=utf-8 +Location: http://127.0.0.1:4455/auth/registration?flow=7430f336-0be0-47d1-b1fc-5cc6fcc3f228 +Set-Cookie: csrf_token=B/3v+RUD5Q7UNzmnp58CR5yhqyAEQL5uNdvmHO3sP/Y=; Path=/; Domain=127.0.0.1; Max-Age=31536000; HttpOnly +Vary: Cookie +Date: Thu, 03 Sep 2020 14:22:44 GMT +Content-Length: 104 + +Found. +``` + +If the `oidc` method is enabled and at least one provider is +configued, the Registration Request Response Payload will include an `oidc` method. The method contains different providers, based on your OpenID Connect Provider configuration: -``` -curl http:///self-service/browser/flows/requests/registration?request=54a9f113-3a7b-4cb8-a553-f072aa4e1622 +```shell script +$ curl -s 'http://127.0.0.1:4433/self-service/registration/flows?id=7430f336-0be0-47d1-b1fc-5cc6fcc3f228' | jq { - id: '54a9f113-3a7b-4cb8-a553-f072aa4e1622', - expires_at: '2020-05-15T11:04:09.342537Z', - issued_at: '2020-05-15T10:04:09.342537Z', - request_url: 'http://127.0.0.1:4433/self-service/browser/flows/registration', - methods: { - oidc: { - method: 'oidc', - config: { - action: 'http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/strategies/oidc/auth/54a9f113-3a7b-4cb8-a553-f072aa4e1622', - method: 'POST', - fields: [ - { - name: 'csrf_token', - type: 'hidden', - required: true, - value: 'J9blMEwxnz6cL7rgcpu1vthggR13RH+7YMS77GBPn9yo7FqPNc9tTsvCQhu7Cu8AAREWXZF2FiaPia26SfrPBA==' - }, - { - name: 'provider', - type: 'submit', - value: 'hydra' - }, + "id": "7430f336-0be0-47d1-b1fc-5cc6fcc3f228", + "type": "browser", + "expires_at": "2020-09-03T14:32:44.060729362Z", + "issued_at": "2020-09-03T14:22:44.060729362Z", + "request_url": "http://127.0.0.1:4433/self-service/registration/browser", + "messages": null, + "methods": { + "oidc": { + "method": "oidc", + "config": { + "action": "http://127.0.0.1:4433/self-service/methods/oidc/auth/7430f336-0be0-47d1-b1fc-5cc6fcc3f228", + "method": "POST", + "fields": [ { - name: 'provider', - type: 'submit', - value: 'google' + "name": "csrf_token", + "type": "hidden", + "required": true, + "value": "LJ3o59zXjukFs1004vyn3QrWDrfutW2e0Iaqo/9Ck6srYAceydRr59GEZJNFY6Walnell+r10/DlXUy/Eq6sXQ==" }, { - name: 'provider', - type: 'submit', - value: 'github' - } - ] - } - }, - password: { - method: 'password', - config: { - action: 'http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/registration/strategies/password?request=54a9f113-3a7b-4cb8-a553-f072aa4e1622', - method: 'POST', - fields: [ - { - name: 'csrf_token', - type: 'hidden', - required: true, - value: 'J9blMEwxnz6cL7rgcpu1vthggR13RH+7YMS77GBPn9yo7FqPNc9tTsvCQhu7Cu8AAREWXZF2FiaPia26SfrPBA==' - }, - { - name: 'password', - type: 'password', - required: true - }, - { - name: 'traits.email', - type: 'email' - }, - { - name: 'traits.website', - type: 'url' + "name": "provider", + "type": "submit", + "value": "github" } ] } @@ -163,7 +145,7 @@ curl http:///self-service/browser/flows/requests/registration?requ The next step depends on your Identity JSON Schema and your JsonNet code. We're using the following in this example: -```json title="path/to/identity.traits.json.schema +```json title="path/to/identity.traits.json.schema" { "$id": "https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json", "$schema": "http://json-schema.org/draft-07/schema#", @@ -224,57 +206,59 @@ actually use email addresses in `sub` fields and also does not include the `website` claim: ```shell script -$ curl http:///self-service/browser/flows/requests/registration?request=54a9f113-3a7b-4cb8-a553-f072aa4e1622" +$ curl -s 'http://127.0.0.1:4433/self-service/registration/flows?id=44c8d084-5623-437e-8fe2-bed2e09c5076' | jq { - id: '54a9f113-3a7b-4cb8-a553-f072aa4e1622', - // ... - active: 'oidc', // <-- this is now set - methods: { - oidc: { - method: 'oidc', - config: { - action: 'http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/strategies/oidc/auth/54a9f113-3a7b-4cb8-a553-f072aa4e1622', - method: 'POST', - // Errors can be included here, for example: - // "errors": [ - // { - // "message": "Authentication failed because no id_token was returned. Please accept the \"openid\" permission and try again." - // } - // ] - fields: [ + "id": "44c8d084-5623-437e-8fe2-bed2e09c5076", + "type": "browser", + "expires_at": "2020-09-03T14:33:54.521832263Z", + "issued_at": "2020-09-03T14:23:54.521832263Z", + "request_url": "http://127.0.0.1:4433/self-service/registration/browser", + "active": "oidc", + "messages": null, + "methods": { + "oidc": { + "method": "oidc", + "config": { + "action": "http://127.0.0.1:4433/self-service/methods/oidc/auth/44c8d084-5623-437e-8fe2-bed2e09c5076", + "method": "POST", + "fields": [ { - name: 'csrf_token', - type: 'hidden', - required: true, - value: 'A84oYSplXqtJTkhSipZc/2+tFXCN2gzWAfhmoK049FKM9JfeU5us2x6jsKlDBwZBttyCMGvoZUvutXD2hI2kig==' + "name": "csrf_token", + "type": "hidden", + "required": true, + "value": "zvDuQ/2snq+pHXFi2u08tR9s431fmBfdD8i+bjkDzIc8xEVubcza5HoIwgu2gJZpJywXYSwPLMPcLPE+K55crw==" }, { - name: 'traits.email', - type: 'text', - value: 'superuser@ory.sh' + "name": "traits.email", + "type": "text", + "value": "aeneas@ory.sh" }, { - name: 'traits.website', - type: '', - messages: [ + "name": "traits.website", + "type": "", + "messages": [ { - id: 4000002, - type: 'error', - text: 'Property website is missing.' // <-- because "website" was not set, the user has to fill it out manually. + "id": 4000002, + "text": "Property website is missing.", + "type": "error", + "context": { + "property": "website" + } } ] }, { - name: 'provider', - type: 'submit', - value: 'google' + "name": "provider", + "type": "submit", + "value": "github" } ] } } } } + ``` If the form is valid, ORY Kratos will create the user and respond with a HTTP @@ -287,51 +271,62 @@ the `Set-Cookie` HTTP header. Redirecting the browser to the [Self-Service Login and Registration Endpoint](../user-login-user-registration.mdx#user-login-and-user-registration-process-sequence) -initiates the flow. If the `oidc` method is enabled and at least one provider -is configued, the Login Request Response Payload will include an `oidc` method. -The method contains different providers, based on your OpenID Connect Provider +initiates the flow: + +```shell script +$ curl -s -D - -X GET --cookie cookie.txt --cookie-jar cookie.txt \ + http://127.0.0.1:4433/self-service/login/browser +HTTP/1.1 302 Found +Cache-Control: 0 +Content-Type: text/html; charset=utf-8 +Location: http://127.0.0.1:4455/auth/login?flow=2e87577f-1209-407c-b523-4727d7bbdbd4 +Set-Cookie: csrf_token=HBp3M2EUNggjJ8GFjCUKGnEyvYWWyD5cpIsXAkGJn6I=; Path=/; Domain=127.0.0.1; Max-Age=31536000; HttpOnly +Vary: Cookie +Date: Thu, 03 Sep 2020 14:25:31 GMT +Content-Length: 97 + +Found. +``` + + +If the `oidc` method is enabled and at least one provider is +configued, the Login Request Response Payload will include an `oidc` method. The +method contains different providers, based on your OpenID Connect Provider configuration: -```json5 title="$ curl http:///self-service/browser/flows/requests/login?request=a1c78949-1436-44bd-93ae-a57836be01c7" +```shell script +$ curl -s 'http://127.0.0.1:4433/self-service/login/flows?id=2e87577f-1209-407c-b523-4727d7bbdbd4' | jq + { - id: 'a1c78949-1436-44bd-93ae-a57836be01c7', - expires_at: '2020-05-15T10:49:58.770828Z', - issued_at: '2020-05-15T09:49:58.770829Z', - request_url: 'http://127.0.0.1:4433/self-service/browser/flows/login', - methods: { - // password: ... - oidc: { - method: 'oidc', - config: { - action: 'http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/strategies/oidc/auth/a1c78949-1436-44bd-93ae-a57836be01c7', - method: 'POST', - fields: [ + "id": "2e87577f-1209-407c-b523-4727d7bbdbd4", + "type": "browser", + "expires_at": "2020-09-03T14:35:31.366554235Z", + "issued_at": "2020-09-03T14:25:31.366554235Z", + "request_url": "http://127.0.0.1:4433/self-service/login/browser", + "messages": null, + "methods": { + "oidc": { + "method": "oidc", + "config": { + "action": "http://127.0.0.1:4433/self-service/methods/oidc/auth/2e87577f-1209-407c-b523-4727d7bbdbd4", + "method": "POST", + "fields": [ { - name: 'csrf_token', - type: 'hidden', - required: true, - value: '/Q85ogDm+Hv7D+ca7DUXYBRqmkTdMiIzXrZxt8IXgFHd7rkc8+U1WoWNmScDfJ8/cEju/hUIko5N48GR3rMfag==' + "name": "csrf_token", + "type": "hidden", + "required": true, + "value": "O0e8KWxx1zZeNEgUOxNFvV8dVMrK63MXoxU102lj9n0nXcsaDWXhPn0TiZG3Nk+nLi/pT1wjTUsHniLRKOpp3w==" }, { - name: 'provider', - type: 'submit', - value: 'hydra' - }, - { - name: 'provider', - type: 'submit', - value: 'google' - }, - { - name: 'provider', - type: 'submit', - value: 'github' + "name": "provider", + "type": "submit", + "value": "github" } ] } } }, - forced: false + "forced": false } ``` @@ -339,52 +334,46 @@ The only form validation error that can happen during this flow is that the ID Token is missing because the user did not authorize the `openid` grant (does not apply for `provider: github`): -```json5 title="$ curl http:///self-service/browser/flows/requests/login?request=a1c78949-1436-44bd-93ae-a57836be01c7" +```shell script +$ curl -s 'http://127.0.0.1:4433/self-service/login/flows?id=2e87577f-1209-407c-b523-4727d7bbdbd4' | jq + { - id: 'a1c78949-1436-44bd-93ae-a57836be01c7', - // expires_at, ... - active: 'oidc', // <- this is now set! - methods: { - // password: ... - oidc: { - method: 'oidc', - config: { - action: 'http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/strategies/oidc/auth/a1c78949-1436-44bd-93ae-a57836be01c7', - method: 'POST', - messages: [ + "id": "2e87577f-1209-407c-b523-4727d7bbdbd4", + "type": "browser", + "expires_at": "2020-09-03T14:35:31.366554235Z", + "issued_at": "2020-09-03T14:25:31.366554235Z", + "request_url": "http://127.0.0.1:4433/self-service/login/browser", + "messages": null, + "methods": { + "oidc": { + "method": "oidc", + "config": { + "action": "http://127.0.0.1:4433/self-service/methods/oidc/auth/2e87577f-1209-407c-b523-4727d7bbdbd4", + "method": "POST", + "messages": [ { - id: 4000000, - type: 'error', - text: 'Authentication failed because no id_token was returned. Please accept the "openid" permission and try again.' + "id": 4000000, + "type": "error", + "text": "Authentication failed because no id_token was returned. Please accept the \"openid\" permission and try again." } ], - fields: [ - { - name: 'csrf_token', - type: 'hidden', - required: true, - value: 'viM0pQKXUIthwPklREm/86pdIg3d8CWJOzGOiHtrCW4xGYsae2mi+zYtAd6N2OVNcyy1TTvCTBTUfJjeUt5Ztg==' - }, - { - name: 'provider', - type: 'submit', - value: 'hydra' - }, + "fields": [ { - name: 'provider', - type: 'submit', - value: 'google' + "name": "csrf_token", + "type": "hidden", + "required": true, + "value": "O0e8KWxx1zZeNEgUOxNFvV8dVMrK63MXoxU102lj9n0nXcsaDWXhPn0TiZG3Nk+nLi/pT1wjTUsHniLRKOpp3w==" }, { - name: 'provider', - type: 'submit', - value: 'github' + "name": "provider", + "type": "submit", + "value": "github" } ] } } }, - forced: false + "forced": false } ``` diff --git a/docs/docs/self-service/flows/user-login-user-registration/username-email-password.mdx b/docs/docs/self-service/flows/user-login-user-registration/username-email-password.mdx index 08b6213ae8f..1021348494b 100644 --- a/docs/docs/self-service/flows/user-login-user-registration/username-email-password.mdx +++ b/docs/docs/self-service/flows/user-login-user-registration/username-email-password.mdx @@ -15,9 +15,9 @@ and [Self-Service Flows Documentation](../../../self-service) first. import CodeFromRemote from '@theme/CodeFromRemote' -This document summarizes exemplary request payloads for performing "login or -sign up with email/username and password" flows using the user login and -registration flow with the `password` method. +This document summarizes exemplary flow payloads for performing "login or sign +up with email/username and password" flows using the user login and registration +flow with the `password` method. We will use the following JSON Schema in all examples on this page: @@ -35,14 +35,32 @@ Page Apps (ReactJS, AngularJS, ...). Redirecting the browser to the [Self-Service Login and Registration Endpoint](../user-login-user-registration.mdx#user-login-and-user-registration-process-sequence) -initiates the flow. If the `password` method is enabled, the Registration -Request Response Payload will include a `password` method. +initiates the flow: + +```shell script +$ curl -s -D - -X GET --cookie cookie.txt --cookie-jar cookie.txt \ + http://127.0.0.1:4433/self-service/registration/browser + +HTTP/1.1 302 Found +Cache-Control: 0 +Content-Type: text/html; charset=utf-8 +Location: http://127.0.0.1:4455/auth/registration?flow=9971995f-fb1c-418f-b54c-b677a372af52 +Set-Cookie: csrf_token=/6KyN25oFVMtqEUTGmmUeXtfHgcXGcm6LXr+Oj8su0Y=; Path=/; Domain=127.0.0.1; Max-Age=31536000; HttpOnly +Vary: Cookie +Date: Thu, 03 Sep 2020 13:15:03 GMT +Content-Length: 104 + +Found. +``` + +If the `password` method is enabled, the Registration Flow +Response Payload will include a `password` method. ORY Kratos uses the Identity JSON Schema defined in `identity.default_schema_url` to generate a list of form fields and add it to -the Registration Request. +the Registration Flow. -The identity schema above will result in the following Registration Request +The identity schema above will result in the following Registration Flow ```shell script $ curl -H "Accept: application/json" -s \ @@ -109,9 +127,8 @@ Once the user clicks "Create Account", the payload will be sent to ORY Kratos' Public API. The data will be validated against the Identity JSON Schema (e.g. checking if a required field is missing, if some condition like `minLength` is not fulfilled, ...). If the data is invalid or incomplete, the browser will be -redirected to the same login endpoint with the same request ID. When fetching -that request ID again, error details will be included in the JSON Response, such -as: +redirected to the same login endpoint with the same flow ID. When fetching that +flow ID again, error details will be included in the JSON Response, such as: ```shell script $ curl -H "Accept: application/json" -s \ @@ -185,10 +202,29 @@ the `Set-Cookie` HTTP header. Redirecting the browser to the [Self-Service Login and Registration Endpoint](../user-login-user-registration.mdx#user-login-and-user-registration-process-sequence) -initiates the flow. If the `password` method is enabled, the Login Request -Response Payload will include a `password` method. In contrast to the -Registration sequence, this payload does not change when the Identity JSON -Schema changes: +initiates the flow: + +```shell script +$ curl -s -D - -X GET --cookie cookie.txt --cookie-jar cookie.txt \ + http://127.0.0.1:4433/self-service/login/browser + +HTTP/1.1 302 Found +Cache-Control: 0 +Content-Type: text/html; charset=utf-8 +Location: http://127.0.0.1:4455/auth/login?flow=d5ce5b2b-6dfe-41f0-9bf5-1091d8cc5cc9 +Vary: Cookie +Date: Thu, 03 Sep 2020 14:10:59 GMT +Content-Length: 97 + +Found. +``` + + +If the `password` method is enabled, the Login Flow Response Payload will include a `password` method. + + +In contrast to the Registration +sequence, this payload does not change when the Identity JSON Schema changes: ```shell script $ curl -H "Accept: application/json" -s \ @@ -300,7 +336,7 @@ API clients are applications which do not run in a browser or in a URL (e.g. ### Registration The registration is initiated by making a request to the Registration API Flow -Initialization endpoint: +Initialization Endpoint: ```shell script $ curl -H "Accept: application/json" -s \ @@ -361,12 +397,13 @@ in an error here because the password does not match the password policy: ```shell script # e.g. http://127.0.0.1:4433/self-service/registration/methods/password?flow=d6e0dd24-f5c6-4926-a526-616a9afeed9d -actionUrl=$(echo $(curl -s -X GET -H "Accept: application/json" "http://127.0.0.1:4433/self-service/registration/api") \ +$ actionUrl=$(echo $(curl -s -X GET -H "Accept: application/json" "http://127.0.0.1:4433/self-service/registration/api") \ | jq -r '.methods.password.config.action') -curl -s -X POST -H "Accept: application/json" -H "Content-Type: application/json" \ +$ curl -s -X POST -H "Accept: application/json" -H "Content-Type: application/json" \ -d '{"traits.email": "api@user.org", "password": "123456", "traits.name.first": "API", "traits.name.last": "User"}' \ "$actionUrl" | jq + { "id": "f7e4dfeb-20b1-466a-8cdc-8575070e3c55", "type": "api",