# AuthBasic Handler

## Presentation

The AuthBasic Handler is a special Handler that will us AuthBasic to authenticate to a virtual host, and then play authorizations rules to allow access to the virtual host.

The Handler will send a WWW-Authenticate header to the client, to request user and password, and then check the credentials using SOAP getCookies web service. When session is granted, the Handler will then check the authorizations like the standard Handler.

This can be useful to allow an third party application to access a virtual host with users credentials by sending a Basic challenge to it.

## Configuration

### Virtual host

#### Apache

Configure the virtual host like other protected virtual host but use AuthBasic Handler instead of default Handler.

    PerlModule Lemonldap::NG::Handler::Specific::AuthBasic
    <VirtualHost *:80>
           ServerName basic.example.com

           # Load AuthBasic Handler
           PerlHeaderParserHandler Lemonldap::NG::Handler::Specific::AuthBasic

           ...

    </VirtualHost>

If LemonLDAP::NG portal is protected by SSL with a self-signed certificate, you can add this line to accept it:

    PerlSetEnv PERL_LWP_SSL_VERIFY_HOSTNAME 0

#### Nginx

Since 1.9.6, LLNG FastCGI server can handle AuthBasic handler. To call it, you just have to add `fastcgi_param LLTYPE authbasic;` in the FastCGI server call and remove `error_page 401` directive:

    location = /lmauth {
      internal;
      include /etc/nginx/fastcgi_params;
      fastcgi_pass unix:/var/run/llng-fastcgi-server/llng-fastcgi.sock;
      fastcgi_param LLTYPE authbasic;

      # Drop post datas
      fastcgi_pass_request_body  off;
      fastcgi_param CONTENT_LENGTH "";

      # Keep original hostname
      fastcgi_param HOST $http_host;

      # Keep original request (LLNG server will received /llauth)
      fastcgi_param X_ORIGINAL_URI  $request_uri;
    }
    location / {
      ...
      ##################################
      # CALLING AUTHENTICATION         #
      ##################################
      auth_request /lmauth;
      auth_request_set $lmremote_user $upstream_http_lm_remote_user;
      auth_request_set $lmlocation $upstream_http_location;
      # Remove this for AuthBasic handler
      #error_page 401 $lmlocation;
      ...
    }

### Handler parameters

No parameters needed. But you have to allow sessions web services, see SOAP sessions backend.