--- name: "Mojolicious::Plugin::OAuth2" section: "3pm" platform: "linux" package: "libmojolicious-plugin-oauth2-perl" version: "2.02-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Mojolicious::Plugin::OAuth2" --- # Mojolicious::Plugin::OAuth2(3pm) Auth against OAuth2 APIs including OpenID Connect ## NAME Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs including OpenID Connect ## SYNOPSIS ### Example application ``` use Mojolicious::Lite; plugin OAuth2 => { providers => { facebook => { key => 'some-public-app-id', secret => $ENV{OAUTH2_FACEBOOK_SECRET}, }, }, }; get '/connect' => sub { my $c = shift; my %get_token = (redirect_uri => $c->url_for('connect')->userinfo(undef)->to_abs); return $c->oauth2->get_token_p(facebook => \%get_token)->then(sub { # Redirected to Facebook return unless my $provider_res = shift; # Token received $c->session(token => $provider_res->{access_token}); $c->redirect_to('profile'); })->catch(sub { $c->render('connect', error => shift); }); }; ``` See "register" for more details about the configuration this plugin takes. ### Testing Code using this plugin can perform offline testing, using the "mocked" provider: ``` $app->plugin(OAuth2 => {mocked => {key => 42}}); $app->routes->get('/profile' => sub { my $c = shift; state $mocked = $ENV{TEST_MOCKED} && 'mocked'; return $c->oauth2->get_token_p($mocked || 'facebook')->then(sub { ... }); }); ``` See Mojolicious::Plugin::OAuth2::Mock for more details. ### Connect button You can add a "connect link" to your template using the "oauth2.auth\_url" helper. Example template: ``` Click here to log in: <%= link_to 'Connect!', $c->oauth2->auth_url('facebook', scope => 'user_about_me email') %> ``` ## DESCRIPTION This Mojolicious plugin allows you to easily authenticate against a OAuth2 \ or OpenID Connect \ provider. It includes configurations for a few popular providers, but you can add your own as well. See "register" for a full list of bundled providers. To support "OpenID Connect", the following optional modules must be installed manually: Crypt::OpenSSL::Bignum, Crypt::OpenSSL::RSA and Mojo::JWT. The modules can be installed with App::cpanminus: ``` $ cpanm Crypt::OpenSSL::Bignum Crypt::OpenSSL::RSA Mojo::JWT ``` ## HELPERS ### oauth2.auth\_url ``` $url = $c->oauth2->auth_url($provider_name => \%args); ``` Returns a Mojo::URL object which contain the authorize URL. This is useful if you want to add the authorize URL as a link to your webpage instead of doing a redirect like "oauth2.get\_token" does. `%args` is optional, but can contain: - • host Useful if your provider uses different hosts for accessing different accounts. The default is specified in the provider configuration. ``` $url->host($host); ``` - • authorize\_query Either a hash-ref or an array-ref which can be used to give extra query params to the URL. ``` $url->query($authorize_url); ``` - • redirect\_uri Useful if you want to go back to a different page than what you came from. The default is: ``` $c->url_for->to_abs->to_string ``` - • scope Scope to ask for credentials to. Should be a space separated list. - • state A string that will be sent to the identity provider. When the user returns from the identity provider, this exact same string will be carried with the user, as a GET parameter called `"state"` in the URL that the user will return to. ### oauth2.get\_refresh\_token\_p ``` $promise = $c->oauth2->get_refresh_token_p($provider_name => \%args); ``` When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode this helper allows for a token to be refreshed by specifying a `"refresh_token"` in `%args`. Usage is similar to "oauth2.get\_token\_p". ### oauth2.get\_token\_p ``` $promise = $c->oauth2->get_token_p($provider_name => \%args) ->then(sub { my $provider_res = shift }) ->catch(sub { my $err = shift; }); ``` "oauth2.get\_token\_p" is used to either fetch an access token from an OAuth2 provider, handle errors or redirect to OAuth2 provider. `$err` in the rejection handler holds a error description if something went wrong. `$provider_res` is a hash-ref containing the access token from the OAauth2 provider or `"undef"` if this plugin performed a 302 redirect to the provider's connect website. In more detail, this method will do one of two things: - 1\. When called from an action on your site, it will redirect you to the provider's `"authorize_url"`. This site will probably have some sort of "Connect" and "Reject" button, allowing the visitor to either connect your site with his/her profile on the OAuth2 provider's page or not. - 2\. The OAuth2 provider will redirect the user back to your site after clicking the "Connect" or "Reject" button. `$provider_res` will then contain a key "access\_token" on "Connect" and a false value on "Reject". The method takes these arguments: `$provider_name` need to match on of the provider names under "Configuration" or a custom provider defined when registering the plugin. `%args` can have: - • host Useful if your provider uses different hosts for accessing different accounts. The default is specified in the provider configuration. - • redirect Set `"redirect"` to 0 to disable automatic redirect. - • scope Scope to ask for credentials to. Should be a space separated list. ### oauth2.jwt\_decode ``` $claims = $c->oauth2->jwt_decode($provider, sub { my $jwt = shift; ... }); $claims = $c->oauth2->jwt_decode($provider); ``` When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode this helper allows you to decode the response data encoded with the JWKS discovered from `"well_known_url"` configuration. ### oauth2.logout\_url ``` $url = $c->oauth2->logout_url($provider_name => \%args); ``` When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode this helper creates the url to redirect to end the session. The OpenID Connect Provider will redirect to the `"post_logout_redirect_uri"` provided in `%args`. Additional keys for `%args` are `"id_token_hint"` and `"state"`. ### oauth2.providers ``` $hash_ref = $c->oauth2->providers; ``` This helper allow you to access the raw providers mapping, which looks something like this: ``` { facebook => { authorize_url => "https://graph.facebook.com/oauth/authorize", token_url => "https://graph.facebook.com/oauth/access_token", key => ..., secret => ..., }, ... } ``` ## ATTRIBUTES ### providers ``` $hash_ref = $oauth2->providers; ``` Holds a hash of provider information. See "oauth2.providers". ## METHODS ### register ``` $app->plugin(OAuth2 => \%provider_config); $app->plugin(OAuth2 => {providers => \%provider_config, proxy => 1, ua => Mojo::UserAgent->new}); ``` Will register this plugin in your application with a given `%provider_config`. The keys in `%provider_config` are provider names and the values are configuration for each provider. Note that the value will be merged with the predefined providers below. Instead of just passing in `%provider_config`, it is possible to pass in a more complex config, with these keys: - • providers The `%provider_config` must be present under this key. - • proxy Setting this to a true value will automatically detect proxy settings using "detect" in Mojo::UserAgent::Proxy. - • ua A custom Mojo::UserAgent, in case you want to change proxy settings, timeouts or other attributes. Instead of just passing in `%provider_config`, it is possible to pass in a hash-ref "providers" (`%provider_config`) and "ua" (a custom Mojo::UserAgent object). Here is an example to add adddition information like "key" and "secret": ``` $app->plugin(OAuth2 => { providers => { custom_provider => { key => 'APP_ID', secret => 'SECRET_KEY', authorize_url => 'https://provider.example.com/auth', token_url => 'https://provider.example.com/token', }, github => { key => 'APP_ID', secret => 'SECRET_KEY', }, }, }); ``` For OpenID Connect \, `"authorize_url"` and `"token_url"` are configured from the `"well_known_url"` so these are replaced by the `"well_known_url"` key. ``` $app->plugin(OAuth2 => { providers => { azure_ad => { key => 'APP_ID', secret => 'SECRET_KEY', well_known_url => 'https://login.microsoftonline.com/tenant-id/v2.0/.well-known/openid-configuration', }, }, }); ``` To make it a bit easier the are already some predefined providers bundled with this plugin: *dailymotion* Authentication for \ video site. *debian\_salsa* Authentication for \. *eventbrite* Authentication for \ event site. See also \. *facebook* OAuth2 for Facebook's graph API, \. You can find `"key"` (App ID) and `"secret"` (App Secret) from the app dashboard here: \. See also \. *instagram* OAuth2 for Instagram API. You can find `"key"` (Client ID) and `"secret"` (Client Secret) from the app dashboard here: \. See also \. *github* Authentication with Github. See also \. *google* OAuth2 for Google. You can find the `"key"` (CLIENT ID) and `"secret"` (CLIENT SECRET) from the app console here under "APIs & Auth" and "Credentials" in the menu at \. See also \. *vkontakte* OAuth2 for Vkontakte. You can find `"key"` (App ID) and `"secret"` (Secure key) from the app dashboard here: \. See also \. ## AUTHOR Marcus Ramberg - `"mramberg@cpan.org"` Jan Henning Thorsen - `"jhthorsen@cpan.org"` ## LICENSE This software is licensed under the same terms as Perl itself. ## SEE ALSO - • \ - • \ - • \ - • \ - • \