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

Automatic certificate generation works, certificate selection works.

Automatic certificate generation works, certificate selection works. Firefox restart is needed after certificate generation.

chromium / chrome

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.

Starting from Chromium version 49, websites need to be whitelisted in order to use the Key Generation feature. Just visit Debian SSO, then click on the HTTPS padlock and allow the feature on this website.

Once generated, your client certificate will be downloaded but not automatically imported. Clicking on the received file will open chromium certificate manager to import it.

Alternatively, generate a certificate manually, then:

openssl pkcs12 -export -out name.p12 -inkey name.key -in name.crt -nodes

and import name.p12 from the certificate dialog at chrome://settings/certificates or from the command line with:

pk12util -i name.p12 -d sql:$HOME/.pki/nssdb 

curl

You can use local certificates

   curl --key $USER.key --cert $USER.crt https://sso.debian.org/ca/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/ca/test/env

From version 2.11.1-1 on, you can configure local client certificates also permanently via Setup → Network options → SSL options. From this version on, also encrypted keys for client certificates are supported.

lynx

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

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/ca/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.

Internet Explorer

Not supported.

Use with a Yubikey in PIV mode

First, install and configure the base system for use with your Yubikey. Please be sure you've got one that works with the PIV applet. A NEO or NEO-N should work. After that's working, install the needed Yubikey and OpenSC software

sudo apt install yubico-piv-tool opensc-pkcs11 opensc

Next, export your Certificate into PKCS#12 format. This can be found in Iceweasel under Preferences, Advanced, Certificates, View Certificates, click on your @debian.org certificate, and click Backup.

Now, lets configure your PIV card. Lets first set the PIN and PUK code. If you've not done this before, the default PIN is 123456, and PUK is 12345678.

yubico-piv-tool -a change-pin -P 123456 -N ${PIN_HERE}
yubico-piv-tool -a change-puk -P 12345678 -N ${PUK_HERE}

Finally, let's load the Cert

yubico-piv-tool -s 9a -i DebianSSOKey.p12 -K PKCS12 -a set-chuid -a import-key -a import-cert

Verify it's working by going to Preferences, Advanced, Certificates, Security Devices. There should be one under OpenSC with a Description of Yubikey NEO-N. If you don't see this, you might have to tell Firefox about the PKCS#11 .so -- click on "Load" under the Security Devices menu, and add /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so into the browser. The interface should surface.

Documentation for Users

If you have a Debian member's account (i.e. LDAP), you can log into sso.debian.org using your Debian Web Password; otherwise, you can log in using your Alioth account credentials. The SSO front page will let you choose the appropriate option.

Once you are logged in , you will see a list of certificates you have already generated, and can create new ones or revoke existing ones.

Getting a certificate

Check above if your browser is supported.

Click on SSO main page and select the appropriate login method (Debian or Alioth) account 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.

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.

Creating certificates manually

You can also visit SSO site to enroll manually and 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. Once you have logged into the site choose the "Get new certificate" option and then choose "getting a certificate manually", which will walk you through generating a key and the appropriate signed challenge for the site to authenticate you.

Some browser will need a PKCS12 file to import the locally generated certificates:

openssl pkcs12 -export -out certificate.pfx -inkey your_private_key.key -in certificate_you_downloaded_from_sso.crt

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. This is useful if you want to protect only some locations. All SSL directives have to be used at the server level.

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;
     }
}

Old Debian SSO documentation

Debian has a Single Sign-On system for authenticating on web services, based on 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 (announcement).

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:

Troubleshooting

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) :

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