Airlock

 view release on metacpan or  search on metacpan

lib/Airlock/Client.pm  view on Meta::CPAN

package Airlock::Client;

# ABSTRACT: OAuth 2.0 device flow client (RFC 8628)

use Moo;
use Airlock::QR;
use Carp qw( croak );
use HTTP::Tiny;
use JSON::MaybeXS;
use Types::Standard qw( CodeRef InstanceOf Str );
use namespace::autoclean;

our $VERSION = '0.001';


has client_id => (
  is       => 'ro',
  isa      => Str,
  required => 1
);


has scope => (
  is      => 'ro',
  isa     => Str,
  default => ''
);


has issuer => (
  is        => 'ro',
  isa       => Str,
  predicate => 'has_issuer'
);


has device_endpoint => (
  is  => 'lazy',
  isa => Str
);

sub _build_device_endpoint { $_[0]->_discovered('device_authorization_endpoint') }


has token_endpoint => (
  is  => 'lazy',
  isa => Str
);

sub _build_token_endpoint { $_[0]->_discovered('token_endpoint') }


has ua => (
  is  => 'lazy',
  isa => InstanceOf['HTTP::Tiny']
);

sub _build_ua { HTTP::Tiny->new( agent => 'Airlock-Client/'.$VERSION, timeout => 30, verify_SSL => 1 ) }


has on_prompt => (
  is  => 'lazy',
  isa => CodeRef
);

sub _build_on_prompt {
  my ( $self ) = @_;
  return sub {
    my ( $start ) = @_;
    binmode STDERR, ':encoding(UTF-8)';
    print STDERR $self->prompt_text($start);
  };
}


has sleep => (
  is      => 'ro',
  isa     => CodeRef,
  default => sub { sub { sleep $_[0] } }
);


has now => (
  is      => 'ro',
  isa     => CodeRef,
  default => sub { sub { time } }
);


has _discovery => (
  is       => 'lazy',
  init_arg => undef
);

sub _build__discovery {
  my ( $self ) = @_;
  croak __PACKAGE__.'->new needs issuer, or device_endpoint and token_endpoint' unless $self->has_issuer;
  my $url      = $self->issuer =~ s{/+\z}{}r.'/.well-known/openid-configuration';
  my $response = $self->ua->get( $url, { headers => { Accept => 'application/json' } } );
  croak __PACKAGE__.' discovery failed: '.$response->{status}.' '.$response->{reason}.' for '.$url
    unless $response->{success};
  my $data = $self->_decode($response);
  croak __PACKAGE__.' discovery returned no JSON object for '.$url unless %$data;
  croak __PACKAGE__.' discovery is for another issuer: '.$self->_printable( $data->{issuer} // '(none)' )
    unless ( $data->{issuer} // '' ) =~ s{/+\z}{}r eq $self->issuer =~ s{/+\z}{}r;
  return $data;
}

sub _discovered {
  my ( $self, $key ) = @_;
  return $self->_discovery->{$key} // croak __PACKAGE__.' discovery has no '.$key;
}

sub device_grant_type { 'urn:ietf:params:oauth:grant-type:device_code' }

sub start {
  my ( $self ) = @_;
  my $response = $self->_post( $self->device_endpoint, {
    client_id => $self->client_id,
    length $self->scope ? ( scope => $self->scope ) : ()
  } );
  my $data = $self->_decode($response);
  croak __PACKAGE__.'->start failed: '.$self->_reason( $response, $data )
    unless $response->{success} && defined $data->{device_code} && defined $data->{user_code};
  return $data;
}


sub poll {
  my ( $self, $start ) = @_;
  my $interval = $self->_seconds( $start->{interval}, 5 );
  my $deadline = $self->now->() + $self->_seconds( $start->{expires_in}, 600 );
  while ( ( my $left = $deadline - $self->now->() ) > 0 ) {
    $self->sleep->( $interval < $left ? $interval : $left );
    my $response = $self->_post( $self->token_endpoint, {
      grant_type  => $self->device_grant_type,
      device_code => $start->{device_code},
      client_id   => $self->client_id
    } );
    my $data = $self->_decode($response);
    return $data if $response->{success} && defined $data->{access_token};
    my $error = $data->{error} // '';
    next if $error eq 'authorization_pending';
    if ( $error eq 'slow_down' || $response->{status} == 599 ) {
      $interval += 5;
      next;
    }
    croak __PACKAGE__.'->poll failed: '.$self->_reason( $response, $data );
  }
  croak __PACKAGE__.'->poll gave up: the code expired before anyone approved it';
}


sub login {
  my ( $self ) = @_;
  my $start = $self->start;
  $self->on_prompt->($start);
  return $self->poll($start);
}


sub prompt_text {
  my ( $self, $start, %arg ) = @_;
  my $text = 'Open '.$self->_printable( $start->{verification_uri} ).' and enter the code '
    .$self->_printable( $start->{user_code} )."\n";
  return $text unless defined $start->{verification_uri_complete};
  return $text.'Or scan:'."\n".Airlock::QR->new( text => $start->{verification_uri_complete}, quiet => 2 )->terminal(%arg);
}


# A server can send anything. Only a positive whole number of seconds is
# taken; everything else falls back, so a bad value cannot turn the poll loop
# into a busy loop.
sub _seconds {
  my ( $self, $value, $default ) = @_;
  return $default unless defined $value && !ref $value && $value =~ /\A[0-9]{1,9}\z/ && $value > 0;
  return $value + 0;
}

# What the server sent goes to a terminal: nothing but printable ASCII.
sub _printable {
  my ( $self, $text ) = @_;
  $text //= '';
  $text =~ s/[^\x20-\x7E]/?/g;
  return $text;
}

sub _post {
  my ( $self, $url, $form ) = @_;
  return $self->ua->post_form( $url, $form, { headers => { Accept => 'application/json' } } );
}

sub _decode {
  my ( $self, $response ) = @_;
  my $data = eval { decode_json( $response->{content} // '' ) };
  return ref $data eq 'HASH' ? $data : {};
}

sub _reason {
  my ( $self, $response, $data ) = @_;
  return $data->{error}.( defined $data->{error_description} ? ' ('.$data->{error_description}.')' : '' )
    if defined $data->{error} && !ref $data->{error};
  return $response->{status}.' '.( $response->{reason} // '' );
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Airlock::Client - OAuth 2.0 device flow client (RFC 8628)

=head1 VERSION

version 0.001

=head1 SYNOPSIS

    my $client = Airlock::Client->new(
      issuer    => 'https://id.example.org/realms/main',
      client_id => 'my-cli',
      scope     => 'openid profile',
    );

    my $token = $client->login;      # prints code and QR to STDERR, then waits
    print $token->{access_token};

=head1 DESCRIPTION

The other side of the device flow: what a command line tool runs to get a
token. It starts the flow, shows the person where to go, polls the token
endpoint at the pace the server sets, and returns the token response.

It speaks plain RFC 8628 and so works against L<Airlock>, Keycloak, and
anything else that implements the grant, including servers that report errors
with status 200.

=head2 client_id

Required. The client identifier registered with the server.

=head2 scope

Scopes to ask for, separated by spaces. Default: none.

=head2 issuer

The issuer URL. When given, the endpoints are read from
C<< <issuer>/.well-known/openid-configuration >>.

=head2 device_endpoint

The device authorization endpoint. Discovered from C<issuer> unless given.

=head2 token_endpoint

The token endpoint. Discovered from C<issuer> unless given.

=head2 ua

The L<HTTP::Tiny> to use. The default verifies TLS certificates. HTTPS needs
L<IO::Socket::SSL>.

=head2 on_prompt

Coderef called with the device authorization response once the flow has
started. The default prints L</prompt_text> to STDERR.

=head2 sleep

Coderef called with the seconds to wait between polls. For tests.

=head2 now

Coderef returning the current epoch. For tests.

=head2 start

    my $start = $client->start;

Begins the flow. Returns the device authorization response: C<device_code>,
C<user_code>, C<verification_uri>, optionally C<verification_uri_complete>,
C<expires_in> and C<interval>. Croaks when the server refuses.

=head2 poll

    my $token = $client->poll($start);

Waits for the approval. Sleeps the interval the server asked for, never past
the lifetime of the code, adds five seconds on every C<slow_down> and on every
connection failure, and returns the token response. Croaks on
C<access_denied>, C<expired_token>, any other error, and when the code's
lifetime runs out.

=head2 login

    my $token = $client->login;

L</start>, the prompt, then L</poll>.

=head2 prompt_text

    print STDERR $client->prompt_text($start);

What to show the person: where to go, the code, and a QR code of
C<verification_uri_complete> when the server sent one. Takes the options of
L<Airlock::QR/terminal>.

=head1 SUPPORT

=head2 Issues

Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/p5-airlock/issues>.

=head2 IRC



( run in 0.641 second using v1.01-cache-2.11-cpan-99fa8243a42 )