@@ -43,6 +43,34 @@ OAuth 2.0 focuses on client developer simplicity while providing specific author
4343 desktop applications, mobile phones, and living room devices.
4444This is a RubyGem for implementing OAuth 2.0 clients (not servers) in Ruby applications.
4545
46+ Quick example: Convert the following ` curl ` command into a token request using this gem...
47+
48+ ``` shell
49+ curl --request POST \
50+ --url ' https://login.microsoftonline.com/REDMOND_REDACTED/oauth2/token'
51+ --header ' content-type: application/x-www-form-urlencoded'
52+ --data grant_type=client_credentials \
53+ --data client_id=REDMOND_CLIENT_ID \
54+ --data client_secret=REDMOND_CLIENT_SECRET \
55+ --data resource=REDMOND_RESOURCE_UUID
56+ ```
57+
58+ NOTE: In the ruby version, certain params go in the get_token call, rather than in the client creation.
59+
60+ ``` ruby
61+ OAuth2 ::Client .new (
62+ " REDMOND_CLIENT_ID" # client_id
63+ " REDMOND_CLIENT_SECRET" # client_secret
64+ auth_scheme: :request_body , # Other modes are supported: :basic_auth, :tls_client_auth, :private_key_jwt
65+ token_url: " oauth2/token" # relative path, except with leading `/`, then absolute path
66+ site: " https://login.microsoftonline.com/REDMOND_REDACTED"
67+ ). # The base path for token_url when it is relative
68+ client_credentials. # There are many other types to choose from!
69+ get_token(resource: " REDMOND_RESOURCE_UUID"
70+ ```
71+
72+ NOTE: ` header ` - The content type specified in the ` curl ` is already the default!
73+
4674## 💡 Info you can shake a stick at
4775
4876* [ OAuth 2.0 Spec] [ oauth2-spec ]
@@ -265,6 +293,19 @@ OAuth2.configure do |config|
265293end
266294```
267295
296+ This comes from ambiguity in the spec about which token is the right token.
297+ Some OAuth 2.0 standards legitimately have multiple tokens.
298+ You may need to subclass ` OAuth2::AccessToken ` , or write your own custom alternative to it, and pass it in.
299+ Specify your custom class with the ` access_token_class ` option.
300+
301+ If you only need one token you can, as of v2.0.10,
302+ specify the exact token name you want to extract via the ` OAuth2::AccessToken ` using
303+ the ` token_name ` option.
304+
305+ You'll likely need to do some source diving.
306+ This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas.
307+ If you have time and energy please contribute to the documentation!
308+
268309### ` authorize_url ` and ` token_url ` are on site root (Just Works!)
269310
270311``` ruby
@@ -302,7 +343,7 @@ client = OAuth2::Client.new(
302343 site: " https://example.org/nested/directory/on/your/server"
303344 authorize_url: " /jaunty/authorize/"
304345 token_url: " /stirrups/access_token"
305- )
346+ )
306347# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
307348client.auth_code.authorize_url(redirect_uri: " http://localhost:8080/oauth2/callback"
308349# => "https://example.org/jaunty/authorize/?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
0 commit comments