Merge pull request #664 from ruby-oauth/example/Jhipster-UAA-Server

Author: pboling

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - simplified client definitions)
 - document how to implement an OIDC client with this gem in OIDC.md
   - also, list libraries built on top of the oauth2 gem that implement OIDC
+- README: Add example for JHipster UAA (Spring Cloud) password grant, converted from Postman/Net::HTTP
 ### Changed
 ### Deprecated
 ### Removed

README.md

@@ -798,6 +798,55 @@ resp = access.get("/v1/things")
 access = client.password.get_token("jdoe", "s3cret", scope: "read")
 ```
 
+#### Examples
+
+<details>
+<summary>JHipster UAA (Spring Cloud) password grant example (legacy; avoid when possible)</summary>
+
+```ruby
+# This converts a Postman/Net::HTTP multipart token request to oauth2 gem usage.
+# JHipster UAA typically exposes the token endpoint at /uaa/oauth/token.
+# The original snippet included:
+# - Basic Authorization header for the client (web_app:changeit)
+# - X-XSRF-TOKEN header from a cookie (some deployments require it)
+# - grant_type=password with username/password and client_id
+# Using oauth2 gem, you don't need to build multipart bodies; the gem sends
+# application/x-www-form-urlencoded as required by RFC 6749.
+
+require "oauth2"
+
+client = OAuth2::Client.new(
+  "web_app",            # client_id
+  "changeit",           # client_secret
+  site: "http://localhost:8080/uaa",
+  token_url: "/oauth/token",      # absolute under site (or "oauth/token" relative)
+  auth_scheme: :basic_auth,         # sends HTTP Basic Authorization header
+)
+
+# If your UAA requires an XSRF header for the token call, provide it as a header.
+# Often this is not required for token endpoints, but if your gateway enforces it,
+# obtain the value from the XSRF-TOKEN cookie and pass it here.
+xsrf_token = ENV["X_XSRF_TOKEN"] # e.g., pulled from a prior set-cookie value
+
+access = client.password.get_token(
+  "admin",                 # username
+  "admin",                 # password
+  headers: xsrf_token ? {"X-XSRF-TOKEN" => xsrf_token} : {},
+  # JHipster commonly also accepts/needs the client_id in the body; include if required:
+  # client_id: "web_app",
+)
+
+puts access.token
+puts access.to_hash # full token response
+```
+
+Notes:
+- Resource Owner Password Credentials (ROPC) is deprecated in OAuth 2.1 and discouraged. Prefer Authorization Code + PKCE.
+- If your deployment strictly demands the X-XSRF-TOKEN header, first fetch it from an endpoint that sets the XSRF-TOKEN cookie (often "/" or a login page) and pass it to headers.
+- For Basic auth, auth_scheme: :basic_auth handles the Authorization header; you do not need to base64-encode manually.
+
+</details>
+
 ### Refresh Tokens
 
 When the server issues a refresh_token, you can refresh manually or implement an auto-refresh wrapper.

docs/OAuth2.html

@@ -415,7 +415,7 @@ <h3 class="signature first" id="configure-class_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/AccessToken.html

@@ -3069,7 +3069,7 @@ <h3 class="signature " id="to_hash-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Authenticator.html

@@ -883,7 +883,7 @@ <h3 class="signature first" id="apply-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Client.html

@@ -2656,7 +2656,7 @@ <h3 class="signature " id="token_url-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Error.html

@@ -772,7 +772,7 @@ <h3 class="signature " id="response-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/FilteredAttributes.html

@@ -335,7 +335,7 @@ <h3 class="signature first" id="inspect-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/FilteredAttributes/ClassMethods.html

@@ -280,7 +280,7 @@ <h3 class="signature " id="filtered_attributes-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Response.html

@@ -1619,7 +1619,7 @@ <h3 class="signature " id="status-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:43 2025 by
+  Generated on Sun Aug 31 04:29:08 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>