Debian SSO documentation

Debian has a Single Sign-On system for authenticating on web services at , based on Client Certificates. Those certificates can usually be looked up in the browser (e.g. firefox) settings via the menu. As of 2018, debian has a total of five #SSO-enabled_sites of which is geared towards SSO most prominently. In contrast, this very wiki itself cannot handle SSO.

The certificates are separate from the GPG e-mail key which debian members need to have. The SSO certs are web only, while the GPG key is being used to, for example, sign "advocate" statements for new members.

How to obtain a certificate to use Debian SSO:

If you ARE a Debian Developer

  1. Set your SSO password via

  2. Wait a few minutes for propagation,
  3. Use the Debian icon on the left hand side at

Be careful, the login here is not your full mail, but only the part before the @.

If you ARE NOT (yet) a Debian Developer

Since Alioth has been shut down, account registration is disabled, unfortunately that means accounts cannot be created by users anymore. If an account is needed create a ticket in the SSO RT queue either by emailing (the email needs to include the string "Debian RT" in subject) or via RT webfrontend. Please include reasoning for your new account. This has been announced at Debian devel mailing lists. Don't forget to add your OpenPGP key fingerprint. Ensure that your key is available via or Please also inline sign your mail, see the RT wiki for details

Subject: [Debian RT] SSO Account for _____

Please create a SSO Account for me.

Account name: _____-guest
Reason account is needed: _____
OpenPGP key fingerprint: _____


Then use the Alioth SSO icon on the right hand side of - use the given name and password when prompted. is there for testing the certs, but you have to know what you expect to see there, else it will not be too helpful.

Browser support

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

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


Recently (2019-2020) due to both Apache, OpenSSL and Firefox updates, it is necessary to go to about:config and set security.tls.enable_post_handshake_auth to true. It's unclear why this isn't enabled by default, but see the upstream bug report.

After generating a new certificate, either restart the browser or remove active logins (History → Clear Recent History... → "Active Logins" and click "Clear Now") and then try again.

Automatic certificate generation works, certificate selection works.

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

Troubleshooting: If you are sure that your SSO browser certificate is working and still valid but the SSO enabled Debian site is not triggering Firefox's "User Identification Request" dialog box, then it may be that you have visited that same site before and told Firefox back then not to use the SSO certificate for login. Firefox remembers this. Try again with a private browser session; SSO login should work again. The sustainable fix for this is to "Clear Recent History" (namely, "Active Logins") of your webbrowser. Another solution is closing and restarting all Firefox tabs/windows of the current desktop session.

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 


You can use local certificates

   curl --key $USER.key --cert $USER.crt

From version 0.13~20190125-1, you can use local certificates generated by enrolling manually

Concatenate the certificate and key into a single file first:

     cat $USER.crt $USER.key > client_cert.pem

configure elinks to use client certificates (usually in ~/.elinks/elinks.conf):

    set connection.ssl.client_cert.enable = 1
    set connection.ssl.client_cert.file = "client_cert.pem"


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

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.


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


From version 1.17-1 (see 797057) you can use local certificates generated by enrolling manually.

   wget --certificate=$USER.crt --private-key=$USER.key

konqueror, rekonq

Client certificate support needs to be implemented.


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 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 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/ into the browser. The interface should surface.

iOS Safari

Safari does not support generating client certificates, and as user don't have command line access to iOS (unless you jailbreak), you need a computer that can manually generate a certificate.

After generating certificate via manual approach, you need to pack them into PKCS#12 format, note that do NOT leave the password empty as iOS requires PKCS#12 certificate to have password:

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

On iOS, download the certificate via http server (one of the common servers is python3 -m http.server), open the certificate, then go to Settings -> General -> Profiles, and find the certificate to install.

Documentation for Users

If you have a Debian member's account (i.e. LDAP), you can log into 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

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

Documentation for web application owners

A word on the two A's

First of all, be aware that 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 or

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

You can use the 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.

Certificate authority and revocations

On machines the ca certificate and certificate revocation list in /var/lib/dsa/sso will be kept up to date automatically. For this to work the machine has to be added to the sso_rp role in Puppet.

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 is valid for 3 days, after which all certificate checks will fail: make sure the update job runs at least once a day.

Configuring Apache

This is the minimum configuration needed for Apache to negotiate SSL connections using the 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 or username.

For machines:

<VirtualHost *:443>

    # Use the 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


For other machines:

<VirtualHost *:443>

    # Use the CA to validate client certificates
    # Keep these files up to date with update-debsso-ca
    SSLCACertificateFile /srv/
    SSLCARevocationCheck chain
    SSLCARevocationFile /srv/

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

        # Allow access if one does not have a valid certificate
        SSLVerifyClient optional


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

Configuring nginx

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

server {
  listen *:443 ssl;
  ssl_client_certificate /srv/;
  ssl_crl /srv/;
  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/") {
  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;

To send information about the certificate to a reverse-proxied application, use:

server {
  proxy_set_header "X-SSL-Client-S-DN" "$ssl_client_s_dn";
  proxy_set_header "X-SSL-Client-S-DN-CN" "$ssl_client_s_dn_cn";

CategoryAlioth CategoryAlioth