Net::OAuth::Client(3)

NAME
Net::OAuth::Client - OAuth 1.0A Client

SYNOPSIS
  use Net::OAuth::Client;

  # client_id is the Consumer Key, client_secret the Consumer Secret.
  # Framework-agnostic: supply your own redirect and session handling.

  my $client = Net::OAuth::Client->new(
      $client_id,
      $client_secret,
      site               => 'https://provider.example/',
      request_token_path => '/oauth/request_token',
      authorize_path     => '/oauth/authorize',
      access_token_path  => '/oauth/access_token',
      callback           => 'https://you.example/auth/callback',
      session            => \&session,
  );

  # 1. Send the user to the provider to authorize.
  $client->authorize_url;

  # 2. They return to your callback with oauth_token and oauth_verifier.
  my $access_token = $client->get_access_token($token, $verifier);

  # 3. Use the access token to fetch a protected resource.
  my $response = $access_token->get('/profile');
  die $response->status_line unless $response->is_success;
  print $response->decoded_content;

DESCRIPTION
Net::OAuth::Client represents an OAuth client or consumer.

WARNING: Net::OAuth::Client is alpha code. The rest of Net::OAuth is quite stable but this particular module is new, and is under-documented and under-tested.

METHODS

new($client_id, $client_secret, %params)
    Create a new Client

    •   $client_id

        AKA Consumer Key - you get this from the service provider when you register your application.

    •   $client_secret

        AKA Consumer Secret - you get this from the service provider when you register your application.

    •   $params{site}

    •   $params{request_token_path}

    •   $params{authorize_path}

    •   $params{access_token_path}

    •   $params{callback}

    •   $params{session}

    •   $params{allow_v1a_downgrade}

        Permit the fallback to OAuth 1.0 described in "OAUTH 1.0A AND THE CALLBACK CONFIRMATION". Off by default.

  OAUTH 1.0A AND THE CALLBACK CONFIRMATION
Passing a "callback" to "new" selects OAuth 1.0a. In 1.0a the service provider echoes "oauth_callback_confirmed" in its request token response, and later hands the user back with an "oauth_verifier" that the client must present when it exchanges the request token for an access token.

If the provider's request token response does not contain "oauth_callback_confirmed", this client cannot use 1.0a. It used to drop back to plain OAuth 1.0 by itself, and that fallback was invisible: the access token request is then built from the 1.0 message class, which has no "verifier" parameter, so "oauth_verifier" is quietly left off the wire even when the caller passed one to "get_access_token". The verifier is exactly what 1.0a added to stop an attacker starting a flow, getting a victim to authorize the attacker's request token, and then completing the exchange - so an application that asked for 1.0a and silently got 1.0 is open to that, with nothing to tell it so.

"get_request_token" now croaks in that situation instead. An application that has to talk to a provider which is not 1.0a can opt in with

  allow_v1a_downgrade => 1

which restores the fallback and warns rather than dying.

AUTHOR
Originally by Keith Grennan <foss@nearlyfree.org>

Currently maintained by Robert Rothenberg <perl@rhizomnic.com>

LICENSE AND COPYRIGHT
Copyright 2007-2012, 2024-2025 Keith Grennan

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.