Authentication

Owned by Former user (Deleted)
Last updated: Oct 23, 2024 by Mirko Vucicevich
11 min read

Collection of tips / guides for authentication on different platforms targeting University of Waterloo.

NOTE: As of 2024, the recommended mechanism for authentication is DUO OIDC. This requires IST to grant access tokens in order to function.

 

Getting started

NOTE: FAST Members can access fully functional examples w/ localhost client ID on gitlab.

  •  

  • You will need to know your callback URL (depending on your software stack this might be predetermined, check documentation for your libraries!)

  • If doing a reverse proxy to localhost on for example port 8080 it’s critical to firewall that port!

  • Need to contact IST for a client key via a ticket

    • NEW: OpenID Connect

      • ISS-General 2FA https://uwaterloo.atlassian.net/servicedesk/customer/portal/2/group/413/create/1660

      • set summery: “OIDC: add new web client“

      • set select topic you require assistance with: “Duo 2FA support”

      • set Additional comments

        ## The django module uses /oidc/duo/callback/ ## Apache uses /secure/redirect_uri callback URIs: - https://x.x.uwaterloo.ca/oidc/duo/callback/ - https://x-stage.x.uwaterloo.ca/oidc/duo/callback/ *group* in short format, not full DN. claims: winaccountname, group, email, name, given_name, family_name

  • Combining authentication with Grouper defined NEXUS groups can be a robust solution

 

Quick Aside: How OIDC Auth kinda works

For those new to the technology, the basic premise is as follows:

  • Your website sends a https request to the OIDC authentication portal using your client key/secret (this will navigate your user away from your website). Part of the request will be your callback url

  • Some stuff happens on the other site – usually the user will log in and then do some 2FA stuff – you don’t need to worry about it, as we trust the OIDC portal!

  • The portal will redirect to your callback url with an auth token – you can store this info and use parts of it to refresh itself. Honestly this bit gets a bit hairy, so if possible you should probably just use a library.

It’s possible to get AD group information sent through the token information, which can be very useful to separate roles on your website via Grouper.

OIDC development config

During development you will find it helpful to support auth on localhost. The following configuration only supports callbacks to localhost:port/oidc/duo/callback/. We also added a handful of port numbers to keep things simple: 3000,8000,8080,8888,443,80

You can find the secret in the FAST examples gitlab repo linked above

OIDC_AUTH_SERVER=https://sso-4ccc589b.sso.duosecurity.com/oidc/DIUHIIU5GLVCYFDLE7P7/ OIDC_CLIENT_ID=DIUHIIU5GLVCYFDLE7P7 OIDC_CLIENT_SECRET=TODO: ask mirko for key.. or perhaps we share it? OIDC_CALLBACK=/oidc/duo/callback/

OIDC with Apache (mod_auth_openidc)

You can set up OIDC directly on your Apache / httpd server. This allows you to handle authentication outside of the application itself, and instead push REMOTE_USER to your apps for validating users.

Install Apache module (debian/ubuntu)

apt install -y libapache2-mod-auth-openidc # enable module a2enmod auth_openidc

Configure the module and a basic VirtualHost

 

OIDC in Django - django-oidc-auth

django-oidc-auth is a library maintained by @Mirko Vucicevich , @Ryan Goggin and @Steve Weber for simple OIDC auth via Django. It requires Django >= 3 and python >=3.9 (as of Feb 2024)

For the simplest configuration follow the instructions in the provided README.md, as the software has been designed and tested with campus OIDC configurations.

 

ADFS (Active Directory) Deprecated Auth Guides

New projects should avoid using ADFS directly if possible, and use DUO OIDC instead. This documentation is here for reference.

ADFS - Apache (Mellon)

Create self signed key cert pair. Create metadata file and get current FederationMetadata.xml.

Register your MellonSPMetadataFile.xml using the web form: https://uwaterloo.ca/request-tracking-system/adfs-request

Perhaps set these claims:

Install apache and mellon module

For this example you can copy your certs to the following locations, note you might want to review file mode and privileges.

Apache config example using proxypass.

 

example .htaccess

 

JavaScript (express / passport)

There's a million ways to go about this, easiest I (Mirko) have found so far is with Node + ExpressJS + PassportJS.

The following configuration works with these installs:

npm install expressjs@4.18 express-session@1.17 passport@0.6 passport-azure-ad@4.2 cookie-parser@1.4

I'm also using the dotenv package to add some variables from a .env file to process.env

note the example is using node with .mjs files to enable module import / export

index.mjs

In hindsight this isn't very easy at all. If you need help contact Mirko

PHP

I know at least one of you guys has this set up!

Python - Django (django-auth-adfs)

Django supports REMOTE_USER out of the box, so if you've already got that set up you're good to go!

Alternatively Django has a popular package django-auth-adfs for oauth2 SSO. For the SSO solutions once you have your client key from IST follow the guide on the git repo to set up your LOGIN_URL, urls.py, and INSTALLED_APPS, then set the following in your settings.py:

If you've got it all set up you should be able to log in with ADFS, and Django user accounts will be created as normal.

@Former user (Deleted) supports a fork of the adfs-package with duo / SAML all set up (ryan pls fill out)

.NET Framework

When making your ADFS request ignore any instructions posted by IST; say you want it for .NET, you don't need to provide any metadata file. '

Full Framework/OWIN / somewhere in your app Startup

Anywhere after: