Differences between revisions 57 and 58
Revision 57 as of 2015-09-04 10:48:58
Size: 13783
Editor: SimonKainz
Comment: updated lynx specific hints
Revision 58 as of 2015-09-05 13:49:40
Size: 14281
Editor: ?VincentBernat
Comment: Add instructions for nginx
Deletions are marked like this. Additions are marked like this.
Line 183: Line 183:

= Old Debian SSO documentation =

Debian has a Single Sign-On system for authenticating on web services, based on [[http://dacs.dss.ca/|DACS]]. It runs on https://sso.debian.org/ and is sometimes referred to as "web password".

The web password is one way of logging into Debian's single sign-on system. Another way is via an [[Alioth]] account ([[https://lists.debian.org/debian-devel-announce/2014/03/msg00008.html|announcement]]).
=== Configuring nginx ===

This is the minimum configuration needed for nginx to negotiate SSL connections using the sso.debian.org client certificates. The user certificate distinguised name can be found in `$ssl_client_s_dn`.

{{{
server {
  listen *:443 ssl;
  ssl_client_certificate /srv/sso.debian.org/etc/debsso.crt;
  ssl_crl /srv/sso.debian.org/etc/debsso.crt;
  ssl_verify_client on;
  ssl_verify_depth 1;
}
}}}

You can use `ssl_verify_client optional` to not require a certificate. In this case, also check the `$ssl_client_verify` variable.

If you want to limit to some users, you can use something like that:

{{{
if ($ssl_client_s_dn != "/O=Debian SSO client certificate/CN=bernat@debian.org") {
          return 403;
}
}}}

If you want to extract only the CN, use:

{{{
http {
     map $ssl_client_s_dn $ssl_client_s_dn_cn {
        default "";
        ~/CN=(?<CN>[^/]+) $CN;
     }
}
}}}

Debian SSO documentation

Debian has a Single Sign-On system for authenticating on web services, based on Client Certificates. Certificates are issued by https://sso.debian.org/ and can be used on any site that is setup to accept them.

Browser support

This collects the current status and tips for browsers/http client support for sso.debian.org and client certificates.

Please help keeping it up to date by adding your own experience, and tips.

firefox

Tested with: Firefox 38.

Automatic certificate generation works, certificate selection works.

chromium

Tested with: Chromium 44.

Automatic certificate generation works, certificate selection works.

If you want to access a site multiple times using a different certificate or no certificates, you can use an Incognito window.

curl

You can use local certificates generated by enrolling manually:

   curl --key $USER.key --cert $USER.crt https://sso.debian.org/spkac/test/env

Currently affected by at least 797931 and 797934.

links2

From version 2.10-2 (see 797066) you can use local certificates generated by enrolling manually:

     links2 -http.client_cert_key $USER.key -http.client_cert_crt $USER.crt https://sso.debian.org/spkac/test/env

lynx

From version 2.8.9dev6-4 (see 797901) you can use local certificates generated by enrolling manually:

  • Set the configuration options SSL_CLIENT_CERT_FILE and SSL_CLIENT_KEY_FILE in /etc/lynx-cur/lynx.cfg

  • Set the environment variables SSL_CLIENT_CERT_FILE and `SSL_CLIENT_KEY_FILE to their approriate values

  • use the build in Options Menu in Lynx (Key O, entries SSL client certificate/key)

wget

Currently affected by 797057.

Once that is fixed, wget should already support client certificates:

   wget --certificate=$USER.crt --private-key=$USER.key https://sso.debian.org/spkac/test/env

konqueror, rekonq

Client certificate support needs to be implemented.

xombrero

Cannot currently be used even for manual certificate generation because it lacks basic support for httponly cookies, see 797171.

Note that this browser is currently orphaned in Debian.

Tor Browser

As of Tor Browser 5.0.2, enrolling and using the certificate works as long as "Don't record browsing history or website data" is unchecked in the "Privacy and security settings". Not checked yet if it's indeed preserved across browser restarts, though.

Netsurf

netsurf does not currently support client certificate authentication, but 797747 has a patch to make it load and use certificate files provided via environment variables.

Documentation for Users

If you have an account on Debian's LDAP, you can log into sso.debian.org using your Debian Web Password; otherwise, you can log in using your Alioth account credentials.

Once you are logged in, you can click on Manage your certificates to see a list of certificates you have already generated, create new ones or revoke existing ones.

Getting a certificate

Click on Enroll your browser to create a new certificate and save it in your browser. You can choose the certificate validity, and optionally add a comment to easily identify the certificate in the certificate list; everything else happens automatically.

For privacy, the comment is not stored in the certificates, so it can only be seen by sso.debian.org.

You can have as many certificates as you want, with arbitrary durations. Do not worry about certificate expiration, because getting a new certificate just requires two clicks. For example, if you are going on holidays, you are leaving your computer at home and you have some trust in your tablet, you can enroll your tablet with a certificate that expires at the end of your holidays. Feel free to experiment.

You can also create a new certificate manually to obtain a certificate pair on local files, that you can then use with curl, links or any other HTTPS client software that supports client certificates.

Using certificates

You can use this test page to try your certificates. The browser will ask for confirmation before using it, and if you have more than one it will ask you to choose which one you want to use.

SSO-enabled sites

This is a (possibly incomplete) list of sites that work with sso.debian.org certificates:

Documentation for web application owners

A word on the two A's

First of all, be aware that sso.debian.org client certificates only do *authentication*, your web application needs to handle *authorization* on its own. It is very important to understand the distinction clearly: an introduction can be found here and here.

In particular, the certificate only contains the visitor's username, either name@debian.org or name@users.alioth.debian.org.

Do not assume that a @debian.org username belongs to a Debian Developer, because people with guest accounts on Debian machines can generate certificates with @debian.org usernames.

You can use the nm.debian.org public API to check the status of a person in Debian, although in most services there is no need to give Debian Developers more privileges that to other Debian Contributors.

Configuring Apache

This is the minimum configuration needed for Apache to negotiate SSL connections using the sso.debian.org client certificates. Once that is in place, if the user has a valid client certificate you will find a SSL_CLIENT_S_DN_CN variable in the environment with the user@debian.org or user@users.alioth.debian.org username.

For debian.org machines:

<VirtualHost *:443>

    # Use the sso.debian.org CA to validate client certificates
    # These files are kept automatically up to date.
    SSLCACertificateFile /var/lib/dsa/sso/ca.crt
    SSLCARevocationCheck chain
    SSLCARevocationFile /var/lib/dsa/sso/ca.crl

    <Location …>
        # Export data about the certificate to the environment
        SSLOptions +StdEnvVars

        # Allow access if one does not have a valid certificate
        SSLVerifyClient optional
    </Location>

</VirtualHost>

For other machines:

<VirtualHost *:443>

    # Use the sso.debian.org CA to validate client certificates
    # Keep these files up to date with update-debsso-ca
    SSLCACertificateFile /srv/sso.debian.org/etc/debsso.crt
    SSLCARevocationCheck chain
    SSLCARevocationFile /srv/sso.debian.org/etc/debsso.crl

    <Location …>
        # Export data about the certificate to the environment
        SSLOptions +StdEnvVars

        # Allow access if one does not have a valid certificate
        SSLVerifyClient optional
    </Location>

</VirtualHost>

You can use SSLVerifyClient require to refuse access to clients without a valid certificate. See the SSLVerifyClient documentation for more information.

On debian.org machines the ca certificate and certificate revocation list in /usr/lib/dsa/sso will be kept up to date automatically. On other machines, you can use the update-debsso-ca script to keep the files up to date. While the ca certificate will change very rarely, the certificate revocation list changes every time a user revokes a certificate, so you need to set up a daily cron job to keep it up to date. The CRL issued by sso.debian.org is valid for 3 days, after which all certificate checks will fail: make sure the update job runs at least once a day.

Configuring nginx

This is the minimum configuration needed for nginx to negotiate SSL connections using the sso.debian.org client certificates. The user certificate distinguised name can be found in $ssl_client_s_dn.

server {
  listen *:443 ssl;
  ssl_client_certificate /srv/sso.debian.org/etc/debsso.crt;
  ssl_crl /srv/sso.debian.org/etc/debsso.crt;
  ssl_verify_client on;
  ssl_verify_depth 1;
}

You can use ssl_verify_client optional to not require a certificate. In this case, also check the $ssl_client_verify variable.

If you want to limit to some users, you can use something like that:

if ($ssl_client_s_dn != "/O=Debian SSO client certificate/CN=bernat@debian.org") {
          return 403;
}

If you want to extract only the CN, use:

http {
     map $ssl_client_s_dn $ssl_client_s_dn_cn {
        default "";
        ~/CN=(?<CN>[^/]+) $CN;
     }
}

Documentation for Users

Setting up a web password (Debian Developers)

The web password single signon method only works for Debian Developers.

To set up a web password, you need to log on db.debian.org ("update my info") and set the password where it says: Change web password (for https://sso.debian.org/).

Note that the web password is different from the db.debian.org password, and is also different from the sudo password.

Note that after changing the web password via db.debian.org, it takes about 20 minutes for it to be distributed to LDAP, and take effect.

Debian services using the Debian single signon

This is a list of Debian services using the SSO, which you can use to test if your web password works:

Web browser functions needed

The Debian SSO requires these web browser functions to be working normally or whitelisted:

  • cross-sub-domain redirects (foo.debian.org -> sso.debian.org -> foo.debian.org)

  • cross-sub-domain referrer sending (sso.debian.org -> foo.debian.org)

  • cross-sub-domain cookies (debian.org not just sso.debian.org)

Troubleshooting

  • Verify if you can log into the Debian Contributors site.

  • Verify the password on Alioth's LDAP:

    ssh alioth.debian.org
    $ ldapsearch -W -b dc=alioth,dc=debian,dc=org -D uid=$USER,ou=users,dc=alioth,dc=debian,dc=org uid=$USER

Documentation for web application owners

A word on the two A's

First of all, be aware that DACS only does *authentication*, your web application needs to handle *authorization* on its own. It is very important to understand the distinction clearly: an introduction can be found here and here.

Howto setup your web-app with DACS

There is a libapache2-mod-dacs module which needs to be loaded into apache. It needs two places of configuration (refer to mod_auth_dacs docs) :

  • in the filesystem in /etc/dacs
  • in the apache configuration for the appropriate VirtualHost

When the module is loaded, apache passes REMOTE_USER as usual, but it will look like DEBIANORG::DEBIAN:enrico. The format is federation::jurisdiction:username.

Please do not ignore the federation and jurisdiction: they are an indication of the authentication source. When multiple backends are implemented, the same username may stand for different people according to how they authenticate. For example, enrico@identi.ca (or SOMETHING::IDENTICA:enrico) is not the same person as enrico@debian.org (or DEBIANORG::DEBIAN:enrico).

# TODO Some headers are not passed by default because CGI sucked and people didn't realise fcgi and wsgi don't suck that way. What's in these headers, though?
FcgidPassHeader Authorization
Passheader AUTHORIZATION

<VirtualHost *:443>
        # ... 
        
        # Proper invocation
        AddDACSAuth dacs-acs /usr/bin/dacs_acs

        SetDACSAuthMethod dacs-acs external
        SetDACSAuthSiteConf dacs-acs "/etc/dacs/federations/site.conf"
        SetDACSAuthConf dacs-acs /etc/dacs/federations/debian.org/DEBIAN/dacs.conf
        SetDACSAuthDebug Off
        SetDACSAuthPostBuffer 0
        SetDACSAuthEnvBuffer 32768

        <Location />
                # DACS auth
                AuthType DACS
                AuthDACS dacs-acs

                # DACS ACLs can specify different requirements for different
                # paths in your site. They can be tweaked by sending patches to
                # http://anonscm.debian.org/gitweb/?p=mirror/dsa-puppet.git
                # at modules/dacs/files/per-host/nono.debian.org/
                Require valid-user
        </Location>
</VirtualHost>

For more information

Question from a user

Sorry, I did not find a better place (like bugs.debian.org/sso.debian.org)... Would it be possible to set up SSO for the Alioth mailing lists ? That would be awesome (and completely outside my skills...) -- CharlesPlessy