From 0ebd10365d43915614d6b75295bedec75d4d39fa Mon Sep 17 00:00:00 2001
From: Henning Perl <henning.perl@ory.sh>
Date: Tue, 17 Oct 2023 12:07:47 +0200
Subject: [PATCH] feat: document rop grant

---
 .../resource-owner-password-grant.mdx         | 50 +++++++++++++++++++
 src/sidebar.js                                |  1 +
 2 files changed, 51 insertions(+)
 create mode 100644 docs/oauth2-oidc/resource-owner-password-grant.mdx

diff --git a/docs/oauth2-oidc/resource-owner-password-grant.mdx b/docs/oauth2-oidc/resource-owner-password-grant.mdx
new file mode 100644
index 000000000..60a467cd1
--- /dev/null
+++ b/docs/oauth2-oidc/resource-owner-password-grant.mdx
@@ -0,0 +1,50 @@
+---
+id: resource-owner-password-grant
+title: OAuth2 resource owner password credentials grant
+sidebar_label: Resource owner password flow
+---
+
+:::info
+
+The resource owner password credentials grant is a legacy grant that is only supported in Ory Network for enterprise customers.
+Please contact [sales@ory.sh](mailto:sales@ory.sh) for support.
+
+:::
+
+The OAuth 2.0 Resource Owner Password Credentials Grant is an OAuth 2.0 grant where the application exchanges the user's username
+and password for an access token. This grant type is suitable for clients which are highly trusted by the user, such as his or her
+computer operating system or a highly privileged application. This grant type works as follows:
+
+1. The resource owner (i.e., the user) provides his or her username and password directly to the client.
+2. The client sends a POST request with following parameters in the request body using form encoding to the token endpoint:
+
+   - `grant_type`: The value must be `password`.
+   - `client_id`: The ID of the client that is making the request.
+   - `client_secret`: The client secret that is used to authenticate the client. Only necessary if `token_endpoint_auth_method` is
+     set to `"client_secret_post"` in the OAuth2 client.
+   - `username`: The resource owner username.
+   - `password`: The resource owner password.
+
+3. If the credentials are valid, the authorization server responds with an access token. This OAuth 2.0 grant does not support
+   refresh tokens. The client has to ask the user for username and password whenever the access token expires.
+
+To use the Resource Owner Password Credentials Grant, you need to include the "password" grant in the supported grant types. In
+the Ory Console, edit the grant types by creating or editing an OAuth client.
+
+The credentials (username and password) are checked against Ory Identities. The user that is authenticated must already exist.
+
+```mdx-code-block
+import Mermaid from "@site/src/theme/Mermaid";
+
+<Mermaid
+  chart={`sequenceDiagram
+    participant User
+    participant Client
+    participant Authorization Server
+    User->>Client: Provide username and password
+    Client->>Authorization Server: POST /oauth2/token
+    Authorization Server->>Authorization Server: Validate credentials against Ory Identities
+    Authorization Server->>Client: Sends access token
+    Client->>User: Use access token
+`} />
+```
diff --git a/src/sidebar.js b/src/sidebar.js
index e3b757a3c..06cf3ad76 100644
--- a/src/sidebar.js
+++ b/src/sidebar.js
@@ -208,6 +208,7 @@ module.exports = {
         "oauth2-oidc/identity-provider-integration-settings",
         "oauth2-oidc/client-credentials",
         "oauth2-oidc/authorization-code-flow",
+        "oauth2-oidc/resource-owner-password-grant",
         "oauth2-oidc/refresh-token-grant",
         "oauth2-oidc/jwt-access-token",
         "hydra/guides/oauth2-clients",