/ 
LWP-UserAgent-msgraph-0.04
River stage zero No dependents
/ LWP::UserAgent::msgraph

NAME

LWP::UserAgent::msgraph

VERSION

version 0.01

SYNOPSIS

use LWP::UserAgent::msgraph;

#The XXXX, YYYY and ZZZZ are from your Azure App Registration
#Application Permission version
$ua = LWP::UserAgent::msgraph->new(
   appid => 'XXXX',
   secret => 'YYYY',
   tenant => 'ZZZZ',
   grant_type => 'client_credentials');
$joe=$ua->request(GET => '/users/jdoe@some.com');
$dn=$joe->{displayName};

DESCRIPTION

This module allows the interaction between Perl and the MS Graph API service. Therefore, a MS Graph application can be built using Perl. The application must be correctly registered within Azure with the proper persmissions.

This module has the glue for the needed authentication scheme and the JSON serialization so a conversation can be established with MS Graph. This is only middleware. No higher level object abstraction is provided for the MS Graph object data.

CONSTRUCTOR

my $ua=LWP::UserAgent->new(%options);

This method constructs a new LWP::UserAgent::msgraph object. key/value pairs must be supplied in order to setup the object properly. Missing mandatory options will result in error

KEY              MEANING
-------          -----------------------------------
appid            Application (client) ID
secret           shared secret needed for handshake
tenant           Tenant id
grant_type       Authorizations scheme (client_credentials,authorization_code)
console          Indicates whether interaction with a user is possible
redirect_uri     Redirect URI for delegated auth challenge
local_port       tcp port for mini http server. Defaults to 8081

auth

my $token = $ua->auth;             #For app credentiales            
my $token = $ua->auth($challenge); #For delegated authentication

This method performs the authentication handshake sequence with the MS Graph platform. The optional parameter is the authorization code obtained from a challenge with the impersonated user. If this is an application only non-delegated client, then the $challenge is not needed.

If used in a web application, you should have redirected the user to the authendpoint location and then capture the resulting code listening for the redirect_uri.

A special tweak is supplied for console applications with delegated authentication. In that case, if the code is missing, an http localhost miniserver is launched so the user can trigger the challenge himself. This behavior is activated via the console constructor option. The http miniserver is destroyed as soon as the authorization code arrives. In this case, the redirect_uri is automatically set. The miniserver listens by default on http://localhost:8081. Please note that MS Graph allows the use of localhost in the redirect_uri and in that case SSL is not enforced. But still the localhost URL must be registered in Azure.

request

my $object=$ua->request(GET => '/me');
$ua->request(PATCH => '/me', {officeLocation => $mynewoffice});

The request method makes a call to a MS Graph endpoint url and returns the corresponding response object. An optional perl structure might be supplied as the payload (body) for the request.

The MS Graph has a rich set of API calls for different operations. Check the EXAMPLES section for more tips.

code

print "It worked" if ($ua->code == 201);

A code() method is supplied as a convenient way of getting the last HTTP response code.

next

$more=$ua->next();

The next() method will request additional response content after a previous request if a pagination result set happens.

authendpoint

$location=$ua->authendpoint()

Returns the authentication endpoint as an url string, full with the query part. In a delegated authentication mode, you should point the user to this url via a browser in order to get the proper authorization. This is on offline method, the resulting uri is computed from the constructor options

tokenendpoint

$location=$ua->tokenendpoint()

Returns the oauth 2.0 token endpoint as an url string. This url is used internally to get the authentication token.

Changes from the default LWP::UserAgent behavior

This class inherits from LWP::UserAgent, but some changes apply. If you are used to LWP::UserAgent standart tweaks and shortcuts, you should read this.

The request now accepts a perl structure which will be sent as a JSON body to the MS Graph endoint. Instead of an HTTP::Respones object, request() will return whatever object is returned by the MS Graph method, as a perl structure. The <JSON> module is used as a serialization engine.

request() will use the right Authorization header based on the initial handshake. The get(), post(), patch(), delete(), put(), delete() methods are setup so they call the LWP::UserAgent::msgraph version of request(). That is, they would return a perl structure according to the MS Graph method. In particular, post() and patch() accepts a perl structure as the body. All the binding with the HTTP::Request::Common module has been broken.

The simple_request() method is kept unchanged, but will use the right Bearer token authentication. So, if you need more control over the request, you can use this method. You must add the JSON serialization, though.