
# This module is POD-only, but may be converted to a pm if needed. However,
# that shouldn't happen, where implementation-differences should be handled
# in Net::VOOT::* and Sympa::OAuth*

=head1 NAME

Sympa::VOOT::SURFconext - how to use the VOOT plugin with SURFconext

=head1 DESCRIPTION

SURFconext is a service provided by SURFnet Nederland BV (NL)
B<First read> L<Net::VOOT::SURFconext/DETAILS>.

Be sure to have the most recent version of M<Net::VOOT> installed, especially
when you want to address the test environment: that may change location
every once in a while.

=head2 Setting-up a connection to the VOOT test-server

Manual page L<Net::VOOT::SURFconext> explains how to access the test
server.  You need the following facts:

=over 4

=item * identifier

Pick a clear identifier, like C<sympa-uva> for organisation UvA.  This
is the C<client_id> in your configuration.

=item * profile

Always "Web Application".

=item * redirect URI

This will bring people back to your own sympa installation.  The format must
be something like

  https://[your-sympa-hostname]/oauth_ready/surfconext-test

=item * secret

Be warned: everyone logs-in as the same admin user, so can see your secret.
Fill this in as C<client_secret> in your configuration.

=item * allowed scope

Set to "read"

=back

B<Be aware> the registrations in the test-environment are regularly and
unpredictably flushed.  Also, the location of the service may change without
notice.

Now, put in the C<etc/> directory configured by Sympa, a file named
C<voot.conf>.  This file is JSON formatted, containing an ARRAY of
voot providers.  Add this:

  { "voot.ProviderID"   : "surfconext-test",
    "voot.ProviderName" : "SURFconext (test environment)",
    "voot.ServerClass"  : "Net::VOOT::SURFconext",
    "oauth2" :
      { "client_id"     : "$your_identifier",
        "client_secret" : "$your_secret"
      }
  }

B<Note:> all records together need to be encapsulated into an ARRAY (so,
between C<[> and C<]>.


=head2 Setting up the connection to the "live" server

See L<https://wiki.surfnetlabs.nl/display/surfconextdev/> and contact
C<help AT surfconext.nl>  They will provide you with the C<client_id> and
the C<client_secret>.

You need the following settings:

=over 4

=item * identifier

You will get this information from SURFnet.  This is the C<client_id>
in your configuration.

=item * profile

Always "Web Application".

=item * redirect URI

This will bring people back to your own sympa installation.  The format must
be something like

  https://[your-sympa-hostname]/oauth2_ready/surfconext

=item * secret

You will get this from SURFnet.
Fill this in as C<client_secret> in your configuration.

=item * allowed scope

Set to "read"

=back

Add this to your F<etc/voot.conf> file (JSON syntax, encapsulated in an ARRAY):

  { "voot.ProviderID"   : "surfconext",
    "voot.ProviderName" : "SURFconext"
    "voot.ServerClass"  : "Net::VOOT::SURFconext",
    "oauth2" :
      { "client_id"     : "$your_identifier",
        "client_secret" : "$your_secret"
      }
  }

=head1 AUTHORS

Please contact F<solutions AT overmeer.net> if for remarks on this
documentation or problems with the implementation.

=cut
