kivra/oauth2_client

Erlang OAuth2 Client

Oauth2 Client

This library is designed to simplify consuming Oauth2 enabled REST Services. It wraps a restclient and takes care of reauthenticating expired access_tokens when needed.

Flows

Implemented flows are:

• Client Credentials Grant
• Resource Owner Password Credentials Grant

Example

Retrieve a client with access_token using Password Credentials Grant

1> oauth2c:retrieve_access_token(<<"password">>, <<"Url">>, <<"Uid">>, <<"Pwd">>).
{ok, Headers, Client}

Retrieve a client with access_token using Client Credentials Grant

2> oauth2c:retrieve_access_token(<<"client_credentials">>, <<"Url">>, <<"Client">>, <<"Secret">>).
{ok, Headers, Client}

Microsoft Azure AD: Since parameters are different please use <<"azure_client_credentials">> as Type when retrieving an access token for that service. Be sure to set a Scope if you want to access any of the connected APIs.

2> oauth2c:retrieve_access_token(
    <<"azure_client_credentials">>,
    <<"some_tenant_specific_oauth_token_endpoint">>,
    <<"some_registered_app_id">>,
    <<"some_created_key">>,
    <<"https://graph.microsoft.com">>).
{ok, Headers, Client}

The Opaque Client object is to be used on subsequent requests like:

3> oauth2c:request(get, json, <<"Url">>, [200], Client).
{{ok, Status, Headers, Body} Client2}

See restclient for more info on how requests work.

Twitter Example

-module(oauth2c_twitter_example).

-export([ run/0
        ]).

-define(CONSUMER_SECRET, <<"my_consumer_secret">>).
-define(CONSUMER_KEY, <<"my_consumer_key">>).

-define(OAUTH2_TOKEN_URL, <<"https://api.twitter.com/oauth2/token">>).

-define(USER_TIMELINE_URL(User, StrCount),
        <<"https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name="
          , User, "&count=", StrCount>>).

-define(APP_LIMITS_URL(Resources),
        << "https://api.twitter.com/1.1/application/rate_limit_status.json?resources="
           , Resources>>).
run() ->
    application:ensure_all_started(oauth2c),
    application:ensure_all_started(ssl),
    {ok, _Headers, Client} =
        oauth2c:retrieve_access_token(
          <<"client_credentials">>, ?OAUTH2_TOKEN_URL, ?CONSUMER_KEY,
          ?CONSUMER_SECRET),
    {{ok, _Status1, _Headers1, Tweets}, Client2} =
        oauth2c:request(
          get, json, ?USER_TIMELINE_URL("twitterapi", "4"), [200], Client),
    io:format("Tweets: ~p~n", [Tweets]),
    {{ok, _Status2, _Headers2, Limits}, _Client3} =
        oauth2c:request(
          get, json, ?APP_LIMITS_URL("help,users,search,statuses"),
          [200], Client2),
    io:format("Limits: ~p~n", [Limits]),
    ok.

License

The KIVRA oauth2 library uses an MIT license. So go ahead and do what you want!

oauth2_client's Issues

Header names/values aren't converted to strings internally

Since oauth2c relies on restc for its request making it should pass header names and values as strings. It takes binaries according to the type spec but doesn't convert them internally, this needs to change for headers to work.

Version 1.4.3 crashes when fetching an access token

There was a silent change in jsx version 3.0.0 which always adds return_maps to the decode options, unless return_maps is explicitly specified (see: talentdeficit/jsx@fab436e#diff-442484fd845d07345ff2c60c11cb7f83288e6f11299be9b536594b66d3b09d85L75). The README of jsx does seem to confirm this is the default behavior. As a result, most requests for authorization tokens fail with the following, since oauth2c still expects a proplist for access token information.

 =CRASH REPORT==== 27-Mar-2024::18:42:34.779110 ===
   crasher:
     initial call: my_project_conn:init/1
     pid: <0.1107.0>
     registered_name: my_project_conn
     exception error: no function clause matching 
                      proplists:get_value(<<"access_token">>,
                                          #{<<"access_token">> =>
                                                <<"redacted">>,
                                            <<"expires_in">> => 3599,
                                            <<"token_type">> => <<"Bearer">>},
                                          undefined) (proplists.erl, line 215)
       in function  oauth2c:do_retrieve_access_token/2 (/my_project/_build/default/lib/oauth2_client/src/oauth2c.erl, line 229)
       in call from oauth2c:get_access_token/2 (/my_project/_build/default/lib/oauth2_client/src/oauth2c.erl, line 381)
       in call from oauth2c:ensure_client_has_access_token/2 (/my_project/_build/default/lib/oauth2_client/src/oauth2c.erl, line 215)
       in call from oauth2c:request/8 (/my_project/_build/default/lib/oauth2_client/src/oauth2c.erl, line 201)
       in call from my_project_conn:handle_call/3 (/my_project/src/my_project_conn.erl, line 26)
       in call from gen_server:try_handle_call/4 (gen_server.erl, line 661)
       in call from gen_server:handle_msg/6 (gen_server.erl, line 690)
     ancestors: [my_project_sup,<0.1086.0>]
     message_queue_len: 0
     messages: []
     links: [<0.1087.0>]
     dictionary: []
     trap_exit: false
     status: running
     heap_size: 17731
     stack_size: 27
     reductions: 73174
   neighbours:

Version 1.4.2 still works fine, as this uses a 2.x release of jsx (or more accurately, the version of restclient that 1.4.2 depends on uses a 2.x release).

For the sake of providing some reproducing code, here's a lightly edited version of the code I used to reproduce this (though I would be surprised if it weren't reproducible with most flows),

  OAuthClient = oauth2c:from_service_account_file(Path, <<"my-scope">>),
  Res = oauth2c:request(
    post,
    json,
    <<"https://myapi/resource">>,
    [],
    [],
    {}},
    OAuthClient
  ),

I think that this patch would solve the issue, or at the very least put you closer to solving the issue #29

Adding a test/sample of application-only-auth to twitter?

is it possibile to have a sample of application-only-auth to twitter?

https://dev.twitter.com/docs/auth/application-only-auth

Thanks
Matteo
http:///www.redaelli.org/matteo/

custom request helper

wonder if the internal cowboy_client would fit instead or alongside of restc?
e.g. https://github.com/dvv/social/blob/master/src/cowboy_request.erl#L27

Dropbox OAuth2 grant type not supported

Hi there.
I wanted to use the oauth2_client with the Dropbox Oauth2 api. But it seems that the client in restricted to only two 'grant_type' (azure_client_credentials and client_credentials), while the dropbox api uses "authorization_code" as 'grant_type' https://www.dropbox.com/developers/documentation/http/documentation#oauth2-token
Is it possible to integrate the 'grant_type' fro Dropbox or at least let users to be free to use their own 'grant_type' in token retrieving request.

Thanks

Bearer auth/Google API Access

Hi -

I made some updates to allow for token types (to facilitate access to Google APIs). Are you maintaining this and are you accepting pull requests to add new features?

an example of authenticating against well-known providers wanted

Google, Facebook, Twitter, LinkedIn would be nice.
TIA,
--Vladimir

Hex package

Would be great to make this and restclient hex packages :)