NAME

Yancy::Plugin::Auth::OAuth2 - Authenticate using an OAuth2 provider

VERSION

version 1.065

SYNOPSIS

    use Mojolicious::Lite;
    plugin Yancy => {
        backend => 'sqlite://myapp.db',
    };
    app->yancy->plugin( 'Auth::OAuth2' => {
        client_id => 'CLIENT_ID',
        client_secret => 'SECRET',
        authorize_url => 'https://example.com/auth',
        token_url => 'https://example.com/token',
    } );

DESCRIPTION

This module allows authenticating using a standard OAuth2 provider by implementing the OAuth2 specification.

OAuth2 provides no mechanism for transmitting any information about the user in question, so this auth may require some customization to be useful. Without some kind of information about the user, it is impossible to know if this is a new user or a returning user or to maintain any kind of account information for the user.

This module composes the Yancy::Auth::Plugin::Role::RequireUser role to provide the require_user authorization method.

METHODS

current_user

Returns the access token of the currently-logged-in user.

logout

Clear any currently-logged-in user.

login_form

Get a link to log in using this OAuth2 provider.

get_authorize_url

    my $url = $self->get_authorize_url( $c );

Get a full authorization URL with query parameters. Override this in a subclass to customize the authorization parameters.

handle_token_p

    my $p = $self->handle_token_p( $c, $token );

Handle the receipt of the token. Override this in a subclass to make any API requests to identify the user. Returns a Mojo::Promise that will be fulfilled when the information is complete.

CONFIGURATION

This plugin has the following configuration options.

client_id

The client ID, provided by the OAuth2 provider.

client_secret

The client secret, provided by the OAuth2 provider.

authorize_url

The URL to start the OAuth2 authorization process.

token_url

The URL to get an access token. The second step of the auth process.

login_label

The label for the button to log in using this OAuth2 provider. Defaults to Login.

Sessions

This module uses Mojolicious sessions to store the login information in a secure, signed cookie.

To configure the default expiration of a session, use Mojolicious::Sessions default_expiration.

    use Mojolicious::Lite;
    # Expire a session after 1 day of inactivity
    app->sessions->default_expiration( 24 * 60 * 60 );

HELPERS

This plugin has the following helpers.

yancy.auth.current_user

Get the current user from the session, if any. Returns undef if no user was found in the session.

    my $user = $c->yancy->auth->current_user
        || return $c->render( status => 401, text => 'Unauthorized' );

yancy.auth.require_user

Validate there is a logged-in user and optionally that the user data has certain values. See "require_user" in Yancy::Plugin::Auth::Role::RequireUser.

    # Display the user dashboard, but only to logged-in users
    my $auth_route = $app->routes->under( '/user', $app->yancy->auth->require_user );
    $auth_route->get( '' )->to( 'user#dashboard' );

yancy.auth.login_form

Returns the rendered login button.

    Login with OAuth2:
    %= $c->yancy->auth->login_form

yancy.auth.logout

Log out any current account from any auth plugin. Use this in your own route handlers to perform a logout.

TEMPLATES

To override these templates, add your own at the designated path inside your app's templates/ directory.

yancy/auth/oauth2/login_form.html.ep

Display the button to log in using this OAuth2 provider.

layouts/yancy/auth.html.ep

The layout that Yancy uses when displaying the login form, the unauthorized error message, and other auth-related pages.

SEE ALSO

Yancy::Plugin::Auth

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Doug Bell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Yancy

perl -MCPAN -e shell
install Yancy