docs: update oidc flow with new services (#6294)

* docs: oidc documentation

* docs: oidc documentation

* Update docs/docs/guides/integrate/login-ui/oidc-standard.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/oidc-standard.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/oidc-standard.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/oidc-standard.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/oidc-standard.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/oidc-standard.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update oidc-standard.mdx

* docs: fix broken links

---------

Co-authored-by: Livio Spring <livio.a@gmail.com>

docs/docs/guides/integrate/login-ui/external-login.mdx

@@ -6,7 +6,7 @@ sidebar_label: External Identity Provider
 ## Flow
 
 The prerequisite for adding an external login (social and enterprise) to your user account is a registered identity provider on your ZITADEL instance or the organization of the user.
-If you haven’t added a provider yet, have a look at the following guide first: [Identity Providers](https://zitadel.com/docs/guides/integrate/identity-providers)
+If you haven’t added a provider yet, have a look at the following guide first: [Identity Providers](/docs/guides/integrate/identity-providers)
 
 ![Identity Provider Flow](/img/guides/login-ui/external-login-flow.png)
 
@@ -20,7 +20,7 @@ Send the following two URLs in the request body:
 2. ErrorURL: Page that should be shown when an error happens during the authentication
 
 In the response, you will get an authentication URL of the provider you like.
-[Start Identity Provider Flow Documentation](https://zitadel.com/docs/apis/resources/user_service/user-service-start-identity-provider-flow)
+[Start Identity Provider Flow Documentation](/docs/apis/resources/user_service/user-service-start-identity-provider-flow)
 
 ### Request
 
@@ -65,7 +65,7 @@ After the user has successfully authenticated, a redirect to the ZITADEL backend
 ZITADEL will take the information of the provider. After this, a redirect will be made to either the success page in case of a successful login or to the error page in case of a failure will be performed. In the parameters, you will provide the intentID, a token, and optionally, if a user could be found, a user ID.
 
 To get the information of the provider, make a request to ZITADEL.
-[Get Identity Provider Information Documentation](https://zitadel.com/docs/apis/resources/user_service/user-service-retrieve-identity-provider-information)
+[Get Identity Provider Information Documentation](/docs/apis/resources/user_service/user-service-retrieve-identity-provider-information)
 
 ### Request
 ```bash
@@ -90,8 +90,8 @@ curl --request POST \
 	},
 	"idpInformation": {
 		"oauth": {
-			"accessToken": "ya29.a0AWY7CknrOORopcJK2XX2fQXV9NQpp8JdkKYx-mQZNrR-wktWWhc3QsepT6kloSCgFPS9N0beEBlEYoY5oYUhfc7VlLHTQz5iECE386pyx5YmTueyeQ9GXk1dAw89gi8KRyjNlJApFsfLJaoiLIvKJLf23eAyXgaCgYKAUMSARESFQG1tDrpnTJ2su8BBO24zfmzgneARw0165",
-			"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijg1YmE5MzEzZmQ3YTdkNGFmYTg0ODg0YWJjYzg0MDMwMDQzNjMxODAiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJhenAiOiIxODI5MDIwMjY1MDgtdW1taXQ3dHZjbHBnM2NxZmM4b2ljdGE1czI1aGtudWwuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJhdWQiOiIxODI5MDIwMjY1MDgtdW1taXQ3dHZjbHBnM2NxZmM4b2ljdGE1czI1aGtudWwuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJzdWIiOiIxMTEzOTI4MDU5NzU3MTU4NTY2MzciLCJoZCI6InJvb3RkLmNoIiwiZW1haWwiOiJmYWJpZW5uZUByb290ZC5jaCIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJhdF9oYXNoIjoidGN5X25JTkZHNnFhRTBZTWFsQzZGdyIsIm5hbWUiOiJGYWJpZW5uZSBCw7xobGVyIiwicGljdHVyZSI6Imh0dHBzOi8vbGgzLmdvb2dsZXVzZXJjb250ZW50LmNvbS9hL0FBY0hUdGY5NzNRNk5IOEt6S1RNRVpFTFBVOWx4NDVXcFE5RlJCdXhGZFBiPXM5Ni1jIiwiZ2l2ZW5fbmFtZSI6IkZhYmllbm5lIiwiZmFtaWx5X25hbWUiOiJCw7xobGVyIiwibG9jYWxlIjoiZGUiLCJpYXQiOjE2ODY4MTE0NjUsImV4cCI6MTY4NjgxNTA2NX0.PwlAHRM44e8eYyHzdfotOrcq5GZc4D15mWvN3rGdoDmu2RRgb4T0nDgkY6AVq2vNJxPfbiB1jFtNP6dgX-OgLIxNXg_tJJhwFh-eFPA37cIiv1CEcgEC-q1zXFIa3HrwHLreeU6i7C9JkDrKpkS-AKat1krf27QXxrxHLrWehi5F2l1OZuAKFWYaYmJOd0sVTDBA2o5SDcAiQs_D4-Q-kSl5f0gh607YVHLv7zjyfHtAOs7xPEkNEUVcqGBke2Zy9kAYIgiMriNxLA2EDxFtSyWnf-bCXKnuVX2hwEY0T0lUPrOAVkz7MEOKiacE2xAOczoQvl-wECU0UofLi8XZqg"
+			"accessToken": "ya29...",
+			"idToken": "ey..."
 		},
 		"idpId": "218528353504723201",
 		"rawInformation": {
@@ -103,7 +103,7 @@ curl --request POST \
 				"hd": "mouse.com",
 				"locale": "de",
 				"name": "Minnie Mouse",
-				"picture": "https://lh3.googleusercontent.com/a/AAcKTtf973Q6NH8KzKTMEZELPU9lx45WpQ9FRBuxFdPb=s96-c",
+				"picture": "https://lh3.googleusercontent.com/a/AAcKTtf973Q7NH8KzKTMEZELPU9lx45WpQ9FRBuxFdPb=s96-c",
 				"sub": "111392805975715856637"
 			}
 		}
@@ -152,7 +152,7 @@ Fill the IdP links in the create user request to add a user with an external log
 The idpId is the ID of the provider in ZITADEL, the idpExternalId is the ID of the user in the external identity provider; usually, this is sent in the “sub”.
 The display name is used to list the linkings on the users.
 
-[Create User API Documentation](https://zitadel.com/docs/apis/resources/user_service/user-service-add-human-user)
+[Create User API Documentation](/docs/apis/resources/user_service/user-service-add-human-user)
 
 #### Request
 ```bash
@@ -190,7 +190,7 @@ curl --request POST \
 If you didn't get a user ID in the parameters to your success page, you know that there is no existing user in ZITADEL with that provider and you can register a new user (read previous section), or link it to an existing account.
 
 If you want to link/connect to an existing account you can perform the add identity provider link request.
-[Add IDP Link to existing user documentation](https://zitadel.com/docs/apis/resources/user_service/user-service-add-idp-link)
+[Add IDP Link to existing user documentation](/docs/apis/resources/user_service/user-service-add-idp-link)
 
 #### Request
 ```bash

docs/docs/guides/integrate/login-ui/oidc-standard.mdx

@@ -2,11 +2,6 @@
 title: OIDC Standard
 ---
 
-:::info
-Not yet implemented, but should give you a general impression of how it will work
-Subscribe to the following issue: https://github.com/orgs/zitadel/projects/2/views/1?filterQuery=oidc&pane=issue&itemId=23181369
-:::
-
 To build your own login ui for your own application it is not necessary to have the OIDC standard included or any additional work that has to be done.
 However, it might make sense, if you want to connect your login to different applications especially if they are not in your control and they rely on the standard.
 
@@ -14,13 +9,135 @@ The following flow shows you the different components you need to enable OIDC fo
 ![OIDC Flow](/img/guides/login-ui/oidc-flow.png)
 
 1. Your application makes an authorization request to your login UI
-2. The login UI takes the requests and sends them to the ZITADEL API. In the request to the ZITADEL API, a header to authenticate your client is needed.
+2. The login UI proxies the request to the ZITADEL API. In the request to the ZITADEL API, a header to identify your client is needed.
 3. The ZITADEL API parses the request and does what it needs to interpret certain parameters (e.g., organization scope, etc.)
-4. Redirect to a predefined, relative URL of the login UI that includes the authrequest ID
-5. Request to ZITADEL API to get all the information from the auth request
-6. Create and update the session till the login flow is complete and the user is authenticated. Make sure to include the auth Request ID in the session
-7. Read the callback URL from the ZITADEL API
+4. Redirect to a predefined, relative URL of the login UI that includes the authrequest ID ("/login?authRequest=")
+5. Request to ZITADEL API to get all the information from the auth request. This is optional and only needed if you like to get all the parsed information from the authrequest-
+6. Authenticate the user in your login UI by creating and updating a session with all the checks you need.
+7. Finalize the auth request by sending the session to the request, you will get the callback URL in the response
 8. Redirect to your application with the callback URL you got in the previous request
 9. All OIDC-specific endpoints have to be accepted in the Login UI and should be proxied and sent to the ZITADEL API
 
 
+## Example
+
+Let's assume you host your login UI on the following URL:
+```
+https://login.example.com
+```
+
+## Authorize Request
+
+A user opens your application and is unauthenticated, the user will then be redirected to your login with the following auth Request:
+```
+https://login.example.com/oauth/v2/authorize?client_id=170086824411201793%40yourapp&redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fauth%2Fcallback&response_type=code&scope=openid%20email%20profile&code_challenge=9az09PjcfuENS7oDK7jUd2xAWRb-B3N7Sr3kDoWECOY&code_challenge_method=S256&login_hint=minnie-mouse```
+```
+
+The auth request includes all the relevant information for the OIDC standard and in this example we also have a login hint for the login name "minnie-mouse".
+
+You now have to proxy the auth request from your own UI to the authorize Endpoint of ZITADEL.
+Make sure to add the user id of your login UI as a header to the request: ```x-zitadel-login-client: <userid>```
+
+Read more about the [Authorize Endpoint Documentation](/docs/apis/openidoauth/endpoints#authorization_endpoint)
+
+The endpoint will redirect you to the domain of your UI on the path /login and add the auth Request ID as parameter.
+```https://login.example.com/login?authRequest=V2_224908753244265546```
+
+### Get Auth Request by ID
+
+With the ID from the redirect before you will now be able to get the information of the auth request.
+[Get Auth Request By ID Documentation](/docs/apis/resources/oidc_service/oidc-service-get-auth-request)
+
+```bash
+curl --request GET \
+  --url https://$ZITADEL_DOMAIN/v2alpha/oidc/auth_requests/V2_224908753244265546 \
+  --header 'Authorization: Bearer '"$TOKEN"''\
+```
+
+Response Example:
+
+```json
+{
+	"authRequest": {
+		"id": "V2_224908753244265546",
+		"creationDate": "2023-07-28T13:47:43.471505Z",
+		"clientId": "224901977648260028@mytestproject",
+		"scope": [
+			"openid",
+			"profile"
+		],
+		"redirectUri": "https://myapp.example.com/auth/callback",
+		"loginHint": "mini@mouse.com"
+	}
+}
+```
+
+### Perform Login
+
+After you have initialized the OIDC flow you can implement the login.
+Implement all the steps you like the user the go trough by [creating](/docs/apis/resources/session_service/session-service-create-session) and [updating](/docs/apis/resources/session_service/session-service-set-session) the user-session.
+
+Read the following resources for more information about the different checks:
+- [Username and Password](./username-password)
+- [External Identity Provider](./external-login)
+- [Passkeys](./passkey)
+- [Multi-Factor](./mfa)
+
+### Finalize Auth Request
+
+To finalize the auth request and connect an existing user session with it you have to update the auth request with the session token.
+On the create and update user session request you will always get a session token in the response.
+
+The latest session token has to be sent to the following request:
+
+Read more about the [Finalize Auth Request Documentation](/docs/apis/resources/oidc_service/oidc-service-create-callback)
+
+Make sure that the authorization header is from the same account that you originally sent in the client id header ```x-zitadel-login-client: <userid>``` on the authorize endpoint.
+```bash
+curl --request POST \
+  --url $ZITADEL_DOMAIN/v2alpha/oidc/auth_requests/V2_224908753244265546 \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Bearer '"$TOKEN"''\
+  --header 'Content-Type: application/json' \
+  --data '{
+  "session": {
+    "sessionId": "225307381909694508",
+    "sessionToken": "7N5kQCvC4jIf2OuBjwfyWSX2FUKbQqg4iG3uWT-TBngMhlS9miGUwpyUaN0HJ8OcbSzk4QHZy_Bvvv"
+  }
+}'
+```
+
+In the response you will get a callback URL to which you have to redirect from your login UI.
+
+Example Response:
+```bash
+{
+	"details": {
+		"sequence": "686",
+		"changeDate": "2023-07-31T08:09:19.314537Z",
+		"resourceOwner": "163840776801878273"
+	},
+	"callbackUrl": "https://myapp.example.com/auth/callback?code=k98NBLrdjVbwQQI-oM_rR_cYHv0k3dqpkqlQX8UXTWVnYSQL9g&state=testd"
+}
+```
+
+### OIDC Endpoints
+
+All OIDC relevant endpoints are provided by ZITADEL. In you login UI you just have to proxy them through and send them directly to the backend.
+
+These are endpoints like:
+- Userinfo
+- Well-known
+- Introspection
+- Token
+- etc
+
+
+### End Session / Logout
+
+The end session endpoint has to be implemented as all the other OIDC endpoints. This means you have to proxy the request from you UI to the ZITADEL.
+In case the ZITADEL backend is not able to determine which session to terminate directly or requires additional approval from the user, it will redirect the browser to the following endpoint:
+
+```/logout?post_logout_redirect=```
+
+Prompt the user to select a session, terminate it using the [corresponding endpoint](/docs/apis/resources/session_service/session-service-delete-session) and send the user to the `post_logout_redirect` URL.