CAS-SSO

The Wikimedia Developer SSO Portal at idp.wikimedia.org is a single sign-on (SSO) infrastructure built on Apereo CAS.

When logging into a CAS-enabled website without an active SSO session you'll be redirected to the CAS login page (https://idp.wikimedia.org/login) The CAS service collects LDAP group memberships and makes them available to services for making authorisation choices. After authentication the users get redirected to the initiating service.

The authentication happens with your Wikimedia developer account. There's also the possibility of adding a second factor using U2F, see below how to enable it.

Instructions for using SSO can be found at Single Sign On.

If you select "Remember Me" during, a long term session is initiated. It lasts for seven days (or until you logout via https://idp.wikimedia.org/logout). This option must only be enabled when working from a machine that only you use. If that's not the case and "Remember Me" is not used, your SSO session will expire after one hour of inactivity.

Service

The source code is in the operations/software/cas-overlay-template repository.

The service runs mainly on idp1005 in Eqiad and idp2005 in Codfw.

Some of the services using CAS-SSO for authentication may rely on having the IPs of the IDP hosts whitelisted (e.g. allow egress to those hosts). This is currently the case for:

zarcillo ( IPs must be added to: https://gerrit.wikimedia.org/r/plugins/gitiles/operations/deployment-charts/+/refs/heads/master/helmfile.d/aux-k8s-services/zarcillo/values.yaml)

Configuring and using WebAuthn / FIDO2 multifactor authentication

Services may select to require the use of multi factor authentication (MFA), in the form of WebAuthn. WebAuthn will require the user to provide a physical hardware device, such as a YubiKey or similar, or a Passkey. If an application requires WebAuthn and the user does not have a device configured, CAS will prompt the user to complete the setup on sign in.

Enabling MFA for you application

First please note that at present 2FA should only be enabled on services available to staff (members of the LDAP ops group).

In the configuration for you application in CAS, add the option "mfa" and set it to ['mfa-webauthn',] as seen in the example below.

profile::idp::services:
  puppetboard:
    id: 1
    service_id: 'https://puppetboard-(idp|saml)test\.wikimedia\.org(/.*)?'
    member_of_exclude: '^cn=tools(beta)?.*,ou=servicegroups,.*$'
    required_groups:
      - ops
      - ops-limited
      - idptest-users
    mfa: ['mfa-webauthn',]

See https://apereo.github.io/cas/7.3.x/mfa/Configuring-Multifactor-Authentication.html for future information about CAS MFA option, but note that our installation only supports mfa-webauthn.

Setting up MFA as a user (staff member)

On first sign in to an application which requires MFA, you will be prompted to setup your MFA solution. You will be asked to name your device, or use the auto-generated default. After this click the "Register" button.

At this point much of the process depends on your own setup. If you use a password manager, such as 1Password, it will prompt you and ask if you wish to use a passkey. If you do not, click the icon for the USB hardware device.

At this point your operating system may choose to intervene, this happens on e.g. macOS, which would like store a passkey in your iCloud keychain. Assuming that we also doesn't want that to happen, click the "More options" button. Again dependent on your browser and operating system, you may be asked if you want to sign in using a QR code, or a hardware token/security key, select the latter. Your security key will now light up, press it to complete the registration.

To continue to the application, click the login button and press down on your security key when it light up. You will now be redirected to the application.

Resetting your MFA configuration

In case you lose your device, or passkey, you may need to remove your existing MFA configuration. To do so SSH to one of the IDP hosts, e.g. idp1005.wikimedia.org and run the cas-remove-webauthn script

$ ssh idp.wikimedia.org
$ sudo cas-remove-webauthn <username>

This removes any configuration from the database and you'll be asked to configure a new device next time you sign in to a MFA enabled application.

Known issues / FAQ

We don't implement full Single Logout yet, will be handled via https://phabricator.wikimedia.org/T233941

What username do services use

When user logs into a CAS protected service a number of attributes are used to authenticate the user to the original services. The main attributes which are used for this are as follows, mapped directly to a user's ldap entry:

cn
uid
memberOf

The memberOf attribute is the one most often used for authorisation. As such, if a user can login to https://idp.wikimedia.org and they are in the correct ldap group for a specific services, then they should be able to login with no issue.

Some services will create local accounts for every user and to do this they need to use a unique attribute representing the user. The majority of services use the uid attribute for this, but some use the cn (for example Gerrit and Gitlab). As such, if the uid and cn are different for your account, you may notice differences when switching between services, however one shouldn't suffer any issues.

One of the areas where we do have issues though is for services expecting to use the REMOTE_USER environment variable for authentication, specifically Icinga. In this case we have a strange combinations of issues:

Our LDAP instance is configured to compare cn in a case insensitive manner
CAS passes the username as entered by the user as an additional value namely cas_user
Apache web servermod_auth_cas maps the cas_user attribute to REMOTE_USER

The combination of theses things means that we can see strange issues when logging into services that key off the REMOTE_USER if users login using mixed or unexpected cases. Currently the only service affected by this is Icinga

Debugging

The first thing to get a user to do is to try and login to https://idp.wikimedia.org directly and ensure they can loging and that the attributes shown for the user looks correct. Further to this you can ask the user to visit https://idp-test.wikimedia.org/ and ensure the output there looks correct.

mod_auth_cas

mod_auth_cas stores session information in /var/cache/apache2/mod_auth_cas/$vhost. As such if an application is protected using mod_auth_cas you should be able to check the user sessions with something like the following

$ sudo grep -lr jbond /var/cache/apache2/mod_auth_cas/                                    
/var/cache/apache2/mod_auth_cas/grafana-rw.wikimedia.org/***REDATED***
$ sudo cat $(!!)
sudo cat $(sudo grep -lr jbond /var/cache/apache2/mod_auth_cas/) 
<cacheEntry xmlns="http://uconn.edu/cas/mod_auth_cas">
<user>jbond</user>
<issued>1642085590748873</issued>
<lastactive>1642085603972189</lastactive>
<path>/d/C0lCOf3Mz/</path>
<ticket>***REDACTED***</ticket>
<attributes>
  <attribute name="org.apereo.cas.authentication.principal.REMEMBER_ME">
        <value>true</value>
  </attribute>
  <attribute name="clientIpAddress">
        <value>192.0.2.42</value>
  </attribute>
  <attribute name="sshPublicKey">
        <value>ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIELDJGi+7kchVkEJNgqGvLOT2UOS4CP5HUSUBdyATdfc jbond@work-laptop</value>
  </attribute>
  <attribute name="isFromNewLogin">
        <value>false</value>
  </attribute>
  <attribute name="mail">
        <value>jbond@wikimedia.org</value>
  </attribute>
  <attribute name="authenticationDate">
        <value>2022-01-10T14:55:50.941850Z</value>
  </attribute>
  <attribute name="bypassMultifactorAuthentication">
        <value>false</value>
  </attribute>
  <attribute name="authnContextClass">
        <value>mfa-u2f</value>
  </attribute>
  <attribute name="successfulAuthenticationHandlers">
        <value>U2FAuthenticationHandler</value>
  </attribute>
  <attribute name="userAgent">
        <value>Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Firefox/78.0</value>
  </attribute>
  <attribute name="cn">
        <value>Jbond</value>
  </attribute>
  <attribute name="credentialType">
        <value>U2FTokenCredential</value>
  </attribute>
  <attribute name="samlAuthenticationStatementAuthMethod">
        <value>urn:oasis:names:tc:SAML:1.0:am:unspecified</value>
  </attribute>
  <attribute name="uid">
        <value>jbond</value>
  </attribute>
  <attribute name="authenticationMethod">
        <value>U2FAuthenticationHandler</value>
  </attribute>
  <attribute name="serverIpAddress">
        <value>127.0.0.1</value>
  </attribute>
  <attribute name="longTermAuthenticationRequestTokenUsed">
        <value>false</value>
  </attribute>
  <attribute name="memberOf">
        <!-- trimmed -->
        <value>cn=wmf,ou=groups,dc=wikimedia,dc=org</value>
        <!-- trimmed -->
  </attribute>
  <attribute name="mfa-method">
        <value>mfa-u2f</value>
  </attribute>
</attributes>
</cacheEntry>

Alerting

DownProbe - idp.wikimedia.org down

Most likely Tomcat or the Apereo CAS application has crashed.

Try restarting Tomcat, this is always safe to do. The service will be unavailable while Tomcat is restarting, but no state is stored within CAS itself, and restarting cannot damage anything.

$ sudo systemctl restart tomcat10

If restarting does not fix the issue, but the standby CAS node is responsive, fail-over to the standby. This is done by updating the record in https://gerrit.wikimedia.org/r/plugins/gitiles/operations/dns/+/refs/heads/master/templates/wikimedia.org.

There are currently two nodes available, one in codfw idp200X.wikimedia.org and idp100X.wikimedia.org in eqiad. If the active, and failed node is idp200X, fail-over to idp100X.

External link

https://idp.wikimedia.org