ruby-oauth · pboling · Aug 31, 2025 · Aug 31, 2025
diff --git a/CHANGELOG.md b/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

diff --git a/README.md b/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.

diff --git a/docs/OAuth2.html b/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>

diff --git a/docs/OAuth2/AccessToken.html b/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>

diff --git a/docs/OAuth2/Authenticator.html b/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>

diff --git a/docs/OAuth2/Client.html b/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>

diff --git a/docs/OAuth2/Error.html b/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>

diff --git a/docs/OAuth2/FilteredAttributes.html b/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>

diff --git a/docs/OAuth2/FilteredAttributes/ClassMethods.html b/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>

diff --git a/docs/OAuth2/Response.html b/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>

diff --git a/docs/OAuth2/Strategy.html b/docs/OAuth2/Strategy.html
@@ -107,7 +107,7 @@ <h2>Defined Under Namespace</h2>
 </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>

diff --git a/docs/OAuth2/Strategy/Assertion.html b/docs/OAuth2/Strategy/Assertion.html
@@ -481,7 +481,7 @@ <h3 class="signature " id="get_token-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>

diff --git a/docs/OAuth2/Strategy/AuthCode.html b/docs/OAuth2/Strategy/AuthCode.html
@@ -483,7 +483,7 @@ <h3 class="signature " id="get_token-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>

diff --git a/docs/OAuth2/Strategy/Base.html b/docs/OAuth2/Strategy/Base.html
@@ -195,7 +195,7 @@ <h3 class="signature first" id="initialize-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>

diff --git a/docs/OAuth2/Strategy/ClientCredentials.html b/docs/OAuth2/Strategy/ClientCredentials.html
@@ -343,7 +343,7 @@ <h3 class="signature " id="get_token-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>

diff --git a/docs/OAuth2/Strategy/Implicit.html b/docs/OAuth2/Strategy/Implicit.html
@@ -420,7 +420,7 @@ <h3 class="signature " id="get_token-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>

diff --git a/docs/OAuth2/Strategy/Password.html b/docs/OAuth2/Strategy/Password.html
@@ -374,7 +374,7 @@ <h3 class="signature " id="get_token-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>

diff --git a/docs/OAuth2/Version.html b/docs/OAuth2/Version.html
@@ -111,7 +111,7 @@ <h2>
 </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>

diff --git a/docs/_index.html b/docs/_index.html
@@ -366,7 +366,7 @@ <h2>Namespace Listing A-Z</h2>
 </div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 2025 by
+  Generated on Sun Aug 31 04:29:07 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>

diff --git a/docs/file.CHANGELOG.html b/docs/file.CHANGELOG.html
@@ -79,15 +79,16 @@ <h3 id="added">Added</h3>
   </li>
   <li>document how to implement an OIDC client with this gem in OIDC.md
     <ul>
-      <li>also, list libraries built on top of the oauth2 gem that implement OIDC
-        <h3 id="changed">Changed</h3>
-        <h3 id="deprecated">Deprecated</h3>
-        <h3 id="removed">Removed</h3>
-        <h3 id="fixed">Fixed</h3>
-        <h3 id="security">Security</h3>
-      </li>
+      <li>also, list libraries built on top of the oauth2 gem that implement OIDC</li>
     </ul>
   </li>
+  <li>README: Add example for JHipster UAA (Spring Cloud) password grant, converted from Postman/Net::HTTP
+    <h3 id="changed">Changed</h3>
+    <h3 id="deprecated">Deprecated</h3>
+    <h3 id="removed">Removed</h3>
+    <h3 id="fixed">Fixed</h3>
+    <h3 id="security">Security</h3>
+  </li>
 </ul>
 
 <h2 id="2013---2025-08-30">
@@ -1244,7 +1245,7 @@ <h2 id="001---2010-04-22">
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.CITATION.html b/docs/file.CITATION.html
@@ -82,7 +82,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.CODE_OF_CONDUCT.html b/docs/file.CODE_OF_CONDUCT.html
@@ -191,7 +191,7 @@ <h2 id="attribution">Attribution</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.CONTRIBUTING.html b/docs/file.CONTRIBUTING.html
@@ -274,7 +274,7 @@ <h4 id="manual-process">Manual process</h4>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.FUNDING.html b/docs/file.FUNDING.html
@@ -104,7 +104,7 @@ <h1 id="another-way-to-support-open-source-software">Another Way to Support Open
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.LICENSE.html b/docs/file.LICENSE.html
@@ -60,7 +60,7 @@
       <div id="content"><div id='filecontents'>MIT License<br><br>Copyright (c) 2017-2025 Peter H. Boling, of Galtzo.com, and oauth2 contributors<br>Copyright (c) 2011-2013 Michael Bleigh and Intridea, Inc.<br><br>Permission is hereby granted, free of charge, to any person obtaining a copy<br>of this software and associated documentation files (the "Software"), to deal<br>in the Software without restriction, including without limitation the rights<br>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell<br>copies of the Software, and to permit persons to whom the Software is<br>furnished to do so, subject to the following conditions:<br><br>The above copyright notice and this permission notice shall be included in all<br>copies or substantial portions of the Software.<br><br>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR<br>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,<br>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE<br>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER<br>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,<br>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE<br>SOFTWARE.</div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.OIDC.html b/docs/file.OIDC.html
@@ -247,7 +247,7 @@ <h2 id="raw-oidc-with-ruby-oauthoauth2">Raw OIDC with ruby-oauth/oauth2</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.README.html b/docs/file.README.html
@@ -937,6 +937,55 @@ <h3 id="common-flows-end-to-end">Common Flows (end-to-end)</h3>
 <pre class="code language-ruby"><code class="language-ruby">access = client.password.get_token(&quot;jdoe&quot;, &quot;s3cret&quot;, scope: &quot;read&quot;)
 </code></pre>
 
+<h4 id="examples">Examples</h4>
+
+<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 ? =&gt; 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>
+
 <h3 id="refresh-tokens">Refresh Tokens</h3>
 
 <p>When the server issues a refresh_token, you can refresh manually or implement an auto-refresh wrapper.</p>
@@ -1327,7 +1376,7 @@ <h3 id="please-give-the-project-a-star--">Please give the project a star ⭐ ♥
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 2025 by
+  Generated on Sun Aug 31 04:29:07 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>

diff --git a/docs/file.REEK.html b/docs/file.REEK.html
@@ -61,7 +61,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.RUBOCOP.html b/docs/file.RUBOCOP.html
@@ -161,7 +161,7 @@ <h2 id="benefits-of-rubocop_gradual">Benefits of rubocop_gradual</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>

diff --git a/docs/file.SECURITY.html b/docs/file.SECURITY.html
@@ -113,7 +113,7 @@ <h2 id="enterprise-support">Enterprise Support</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Aug 31 04:15:42 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>