NAME

Plack::Auth::SSO::Shibboleth - implementation of Plack::Auth::SSO for Shibboleth

SYNOPSIS

DESCRIPTION

This is an implementation of Plack::Auth::SSO to authenticate behind a Shibboleth Service Provider (SP)

It inherits all configuration options from its parent.

CONFIG

error_path

This option is inherited by its parent class Plack::Auth::SSO, but cannot be used unfortunately

because an SP will never allow an invalid request to be passed to the backend. This should be configured in

/etc/shibboleth/shibboleth2.xml ( cf. https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPErrors ).

request_type

* "env": Shibboleth SP sends attributes using environment variables (CGI and FCGI)

* "header": Shibboleth SP sends attributes using headers (proxy)

Default is "env"

shib_session_id_field

Field where Shibboleth SP stores the session id.

Default is "Shib-Session-ID"

shib_application_id_field

Field where Shibboleth SP stores the application id.

Default is "Shib-Application-ID"

uid_field

Field to be used as uid

Default is "eppn"

info_fields

Fields to be extracted from the environment/headers

auth_sso output

{

    package => "Plack::Auth::SSO::Shibboleth",

    package_id => "Plack::Auth::SSO::Shibboleth",

    #configured by "uid_field"
    uid => "<unique-identifier>",

    #configured by "info_fields". Empty otherwise
    info => {
        attr1 => "attr1",
        attr2 => "attr2"
    },

    #Shibboleth headers/environment variables
    extra => {
        "Shib-Session-Id" => "..",
        "Shib-Application-Id" => "..",
        "Shib-Identity-Provider" => "https://path.to/shibboleth./idp",
        "Shib-Authentication-Instant" => "",
        "Shib-Authentication-Method" => "POST",
        "Shib-AuthnContext-Class" => "..",
        "Shib-AuthnContext-Decl" => "..",
        "Shib-Handler" => "..",
        "Shib-Session-Index" => ".."
        "Shib-Cookie-Name" => ".."
    },

    #We cannot access the original SAML response, so we rely on the headers/environment
    response => {
        content_type => "application/json",
        content => "<headers/environment serialized as json>"
    }
}

GLOBAL SETUP

This module does not do what it claims to do: authenticating the user by communicating with an external service.

The real authenticating module lives inside the Apache web server, and is called "mod_shib".

That module intercepts all requests to a specific path (e.g. "/auth/shibboleth"), authenticates the user, and, when done, sends the requests to the backend application. As long as a Shibboleth session exists in mod_shib, the request passes through.

That backend application merely receives the end result of the authentication: a list of attributes. The original SAML response from the Shibboleth Identity Provider is not sent.

There are two ways to transfer the attributes from mod_shib to the application:

* the application lives inside Apache (CGI, FCGI). The attributes are sent as environment variables. This is the default situation, and the most secure.

* the application is a separate server, and Apache merely a proxy server. The attributes are sent as headers. This is less secure.

cf. <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeAccess>

This module merely convert these attributes.

SETUP BEHIND PROXY

plack application

use strict;
use Data::Util qw(:check);
use Plack::Auth::SSO::Shibboleth;
use Plack::Builder;
use Plack::Session;
use JSON;

my $uri_base = "https://example.org";

builder {

    enable "Session",

    #mod_shib should intercept all requests to this path
    mount "/auth/shibboleth"  => Plack::Auth::SSO::Shibboleth->new(
        uri_base => $uri_base,
        authorization_path => "/authorize",
        uid_field => "uid",
        request_type => "header",
        info_fields => [qw(mail organizational-unit-name givenname sn unscoped-affiliation entitlement persistent-id)]
    )->to_app();

    mount "/authorize" => sub {

        my $env = shift;
        my $session = Plack::Session->new($env);

        #already logged in. What are you doing here?
        if ( is_hash_ref( $session->get("user") ) ) {

            return [
                302,
                [ Location => "${uri_base}/authorized" ],
                []
            ];

        }

        my $auth_sso = $session->get("auth_sso");

        #not authenticated yet
        unless($auth_sso){

            return [
                302,
                [ "Location" => "${uri_base}/" ],
                []
            ];

        }

        $session->set("user",{ uid => $auth_sso->{uid}, auth_sso => $auth_sso });

        [
            302,
            [ Location => "${uri_base}/authorized" ],
            []
        ];

    };
    mount "/authorized" => sub {
        state $json = JSON->new->utf8(1);

        my $env = shift;
        my $session = Plack::Session->new($env);
        my $user = $session->get("user");

        #not logged in
        unless ( is_hash_ref( $user ) ) {

            return [
                401,
                [ "Content-Type" => "text/plain" ],
                [ "Forbidden" ]
            ];

        }

        #logged in: show user his/her data
        [
            200,
            [ "Content-Type" => "application/json" ],
            [ $json->encode( $user ) ]
        ];

    };

};

httpd.conf

NameVirtualHost *:443
<VirtualHost *:443 >

  ServerName example.org

  #shibd is a background service, so it needs to know the domain and port
  UseCanonicalName on
  UseCanonicalPhysicalPort on

  #configure SSL
  SSLEngine on
  SSLProtocol all -SSLv2 -SSLv3
  SSLHonorCipherOrder on
  SSLCipherSuite "ALL:!ADH:!EXP:!LOW:!RC2:!SEED:!RC4:+HIGH:+MEDIUM HIGH:!SSLv2:!ADH:!aNULL:!eNULL:!NULL !PSK !SRP !DSS"
  SSLCertificateFile /etc/httpd/ssl/server.pem
  SSLCertificateKeyFile /etc/httpd/ssl/server.key
  SSLCACertificateFile /etc/httpd/ssl/server.pem

  #do not proxy Shibboleth paths
  ProxyPass /shibboleth-sp !
  ProxyPass /Shibboleth.sso !

  #proxy all requests to background Plack application
  ProxyPass / http://127.0.0.1:5000/
  ProxyPassReverse / http://127.0.0.1:5000/

  #all request to /auth/shibboleth should be intercepted by mod_shib before
  #sending to background plack application
  <Location /auth/shibboleth>

    AuthName "shibboleth"
    AuthType shibboleth
    Require valid-user
    ShibRequestSetting requireSession true
    ShibRequestSetting redirectToSSL 443

    #necessary to send the attributes in the headers
    ShibUseHeaders On
  </Location>

  #Path to metadata.xml
  Alias /shibboleth-sp /var/www/html/shibboleth-sp

  #handler for Shibboleth Service Provider
  <Location /Shibboleth.sso>
    SetHandler shib-handler
    ErrorDocument 403 /public/403.html
  </Location>

  ProxyRequests Off
  <Proxy *>
    Order Deny,Allow
    Allow from all
  </Proxy>

</VirtualHost>

LOGGING

All subclasses of Plack::Auth::SSO use Log::Any to log messages to the category that equals the current package name.

AUTHOR

Nicolas Franck, <nicolas.franck at ugent.be>

SEE ALSO

Plack::Auth::SSO