Enable authentication via CILogon

[yuvipanda]

Problem statement

Right now we only offer two ways to authenticate for our hubs: GitHub and Google OAuth. However, this falls short in a few ways:

• Many organization-wide hubs will want to authenticate by a given domain (e.g., @berkeley.edu) rather than with an individual list of users
• For organizations that don't with to use Google OAuth or GitHub, we do not have a means of authenticating their users.

Solution

CILogon is an authentication system focused on north american & western european academia. It is the authentication mechanism behind the "eduroam" network and a few others (some more info is here).

It is free for 'academic users' (https://www.cilogon.org/subscribe), and I would like to think we qualify.

If we support CILogon as a login provider, it lets us provide direct institutional logins to a large swath of potential users. This is probably particularly attractive to communities that are specific to an organization / institution, because it allows them to use the same login credentials that they are already using in their institution.

Appetite

1 sprint

If we are integrating this with Auth0, it hopefully shouldn't be too much work to get running. It might take a bit of time to get the authentication approval from the CILogon folks, however.

Guidance / implementation

CILogin has specific instructions on integrating with Auth0, and that is what we should do!

Out of scope

Tasks to complete

2022-01-26

We'll aim to get the following done by the next sprint:

• Get a valid approved client registered with CILogon (https://cilogon.org/oauth2/register)
• Integrate that with our Auth0 setup
• Make it possible to set up CILogon for our hubs: Add cilogon credentials and support #823
• Choose a hub to use as a "demo" or "sandbox" hub for use by 2i2c team
• Test out CILogon with this hub (maybe a demo hub). Two use-cases to consider:
  • Allow all users that match @place.edu pattern
  • Allow a list of users explicitly
  • Allow for a combination of @place.edu users AND 2i2c admin users
• Use this experience to write up documentation about how to do this.
• Investigate a deeper integration with CILogon to use for other authentication patterns as well ➡️ Investigate using CILogon instead of Auth0 #967
  • Look into their service offerings
  • Look into the CILogon Authenticator for JupyterHub
  • Questions to answer:
    • Would this simplify our login process + make it more flexible?
    • Does CILogon have all of the same features that Auth0 does? What are the differences?
    • CILogon costs ~$13,000 a year, is that worth the value we'd get?
    • Is there a "trial run" that we can use to try out their API?
• Come up with some questions we have for the CILogon team in case we'd like a meeting with them

[choldgraf]

After some conversations with @colliand I think that we should bump this up the priority list a little bit, because it will be really useful if we can tell universities that we will "probably" be able to integrate with their institutional SSO via CILogon.

[choldgraf]

We'd like our alpha service to support this (see 2i2c-org/team-compass#262 for ref) , so just another note that this deliverable is quite valuable now!

[yuvipanda]

Next step here is to apply for credentials here: https://cilogon.org/oauth2/register. I hope we qualify using them for free? https://www.cilogon.org/subscribe

[GeorgianaElena]

Some updates about this:

I followed the instructions in https://www.cilogon.org/auth0 and created a new auth0 application that I then registered with CILogon. I provided the 2i2c support email address in the form (hope that's ok).

We need to wait for this to happen now:
An administrator will contact you once your registration request has been approved.

However, even if the request hasn't been approved, we've been provided the client credentials. Should we store these encrypted somewhere in this repo (maybe here)?

[consideRatio]

@GeorgianaElena it seems the request was approved, see https://2i2c.freshdesk.com/a/tickets/38

[GeorgianaElena]

Great! Thanks @consideRatio!

[damianavila]

Should we store these encrypted somewhere in this repo (maybe here)?

That location makes sense to me from the top of my head.

[choldgraf]

Hey @GeorgianaElena - just checking in to see if there's anything that others can do to help you out or unblock on this one!

[GeorgianaElena]

I realized that we're supporting JupyterHub OAuthenticator now, so I'm experimenting with using JupyterHub OAuthenticator to enable CILogon instead of using it through Auth0. I think this issue was opened long before the OAuthenticator addition, so the Auth0 integration might not necessarily be a requirement.

Happy to hear people's ideas about this.

Thank you for asking, @choldgraf!

UPDATE:
Ready to draw some conclusions. Will come back with details.

[GeorgianaElena]

Authentication via CILogon status

1. Why not use JupyterHub CILogonOAuthenticatior?

Now that we support authentication via JupyterHub Native OAuthenticator, why not use CILogonOAuthenticatior directly, without going through Auth0?

Advantages

• CILogonOAuthenticatior natively supports restricting access based on a list of allowed idps
• One CILogon client for all the hubs (similar with Auth0), without adding the Auth0 layer of complexity
• We don't have to maintain or worry about the CILogon social connection added manually to our 2i2c account

Negatives

• When registering the CILogon client, I had to provide the list of allowed callback URLs. All allowed_callback_urls that we intend to use need to be in this list and need to be known at the time of client registration. Otherwise, any changes to this list can only happen through an email sent to CILogon (and we cannot know these in advance because they are based on hub URLs).

2. Integrate CILogon with our Auth0 setup

This has been successfull and #823 adds support for automating enabling this connection from our config files.
We only needed to list the 2i2c auth0 domain in the callback_url list during CILogon registration, and after CILogon authentication, Auth0 knows how to redirect back to each hub's address.

HOWEVER

• Restricting users based on idp will be ugly:
  • Mills hub username pattern example:

    infrastructure/config/hubs/cloudbank.cluster.yaml

    Line 367 in d3da0f3

    username_pattern: '^(.+@mills\.edu|yuvipanda@2i2c\.org|choldgraf@2i2c\.org|georgianaelena@2i2c\.org|sgibson@2i2c\.org|erik@2i2c\.org|damianavila@2i2c\.org|aculich@berkeley\.edu|jpercy@berkeley\.edu|deployment-service-check)$'

• Another approach would be to make changes upstream, either in JupyterHub Authenticator or directly in Auth0Oauthenticator(though I'm not sure if it would make sense to have an allowed email domain list in this Auth0 specific authenticator ?)

• Auth0 rules?? (we are only allowed 3 rules I believe, so this is not scalable)

3. Help

I would love help and feedback about which of these two approaches is better, especially:

1. Is there a way to have only the 2i2c.cloud domain in the callback_url list of CILogon and achieve the same redirection behaviour like we do with the 2i2c auth0 domain?
2. If 1'st point ⬆️ is not achievable, what's the best way to "de-uglify" the username_pattern example above and restrict based on identity provider?

[sgibson91]

• When registering the CILogon client, I had to provide the list of allowed callback URLs. All allowed_callback_urls that we intend to use need to be in this list and need to be known at the time of client registration. Otherwise, any changes to this list can only happen through an email sent to CILogon (and we cannot know these in advance because they are based on hub URLs).

To me, this is a big blocker. I'd rather cope with ugly code than need to rely on manual intervention from CILogon

[choldgraf]

So it sounds like our next step here is to:

• Go with @GeorgianaElena's proposed #2 option above in Enable authentication via CILogon #315 (comment)
• Accept that we will have an ugly username_pattern value for CILogon, and try to resolve this in some future issue

Is that right?

[sgibson91]

Yes, I think so

[choldgraf]

I've updated the top comment with a few more next steps that I think are needed to close this out. I also added a few scenarios that we should test to make sure it works as expected!

[choldgraf]

Planning Meeting / Next Steps

How to allow community users + 2i2c users to log-in

• JupyterHub only allows you to authenticate with a single kind of account (e.g. EITHER GitHub OR gmail)
• If we could use an auth provider that supports multiple kinds of logins then we could still use one auth provider, but that provider could authenticate with different email addresses.
• CILogon might be able to allow for multiple login sources. Could we use a university address + a github account?
• Will it be possible to authenticate ourselves if we are using a SSO?
• Could we create a token for an "admin user" and use this instead of the typical sign-in process?
  • This feels like it'd be a security concern, it'd be a "root access" token :-/
• Could we use CILogon instead of Auth0, and just use this to authenticate across all of our
• Could we just use CILogon directly instead of with Auth0?
  • Probably not - this would force us to ask CILogon for every new university to work with

Next steps

• Add documentation about our CILogon setup, so that we can try it out
• Learn more about whether CILogon could provide the multiple authentication pathway

Also opened up #936 to discuss/explore how we can gain access to hubs that use CILogon (or other SSO)

[consideRatio]

@GeorgianaElena as a followup to a [email protected] email received in https://2i2c.freshdesk.com/a/tickets/69, I wanted to note that:

1. Jim from the CILogon project suggests that it would be possible to use a paid CILogin API to automate things, which is what I suspect could be directly related to addressing the negative of using CILogonOAuthenticator you've described.

   Negatives

   • When registering the CILogon client, I had to provide the list of allowed callback URLs. All allowed_callback_urls that we intend to use need to be in this list and need to be known at the time of client registration. Otherwise, any changes to this list can only happen through an email sent to CILogon (and we cannot know these in advance because they are based on hub URLs).

   I've respond to Jim that I've forwarded this idea and asked for technical details on the API. Note that so far, from what I can tell, we would require a 12.5k USD/year subscription for access that also comes with some other features described here: https://www.cilogon.org/subscribe.

2. It seems like we have a quite solid connection with people at CILogon, which can be quite big with regards to investing into their tech stack. Jim kindly suggests we shouldn't hesitate to followup with questions.

Misc

• Btw, googling Jim made me find this video where one maybe can pickup some relevant insights about CILogon.
• @GeorgianaElena btw, what a beautifully written summary Enable authentication via CILogon #315 (comment) was!!!!!! ❤️ 🎉 👍

[choldgraf]

Update: Try out the demo hub!

@GeorgianaElena has deployed a JupyterHub at demo.pilot.2i2c.cloud - this can be used to try out things, demo them, etc. She's enabled CILogon with @2i2c.org as an authenticated domain. Give it a shot!

My quick feedback: I really like it! It seems like a nice way to support many different institutional sign-ons, and I really like the simplicity of setup!

Question: how do I "log out" of CILogon?

I tried once with my @2i2c.org address, and this worked really nicely! However, I'd now like to try logging in with my Berkeley address to confirm that I cannot access the hub. I can't figure out how to do this! @GeorgianaElena could you provide guidance? I suspect others will hit the same issue if they accidentally log in with the wrong address first

[GeorgianaElena]

Question: how do I "log out" of CILogon?

Good question @choldgraf, I hadn't noticed. I believe there's something similar with this issue we had some time ago
#422. For CILogon I think we need to also to logout the users out of Identity Provider Session Layer.

I also noticed a similar behavior with the toronto hub 😕 (That one is using AzureAdOAuthenticator) I will open up issues about each of these issues:
➡️ #957
➡️ #956

[GeorgianaElena]

Update

I opened #967 to tackle the remaining bullets of this issue (about changing current Auth0 setup with CILogon) and #957 about the logging out issue that @choldgraf noticed.

I was thinking to add the logging out issue to out Operational list of tasks and discuss more about changing Auth0 with CILogon in its own issue, linked above. WDYT @choldgraf? for me, it feels like since we have CILogon auth, we can close this one?

[choldgraf]

@GeorgianaElena that sounds good to me - my main question is whether we can provide a workaround for people who run into the issue described in #957 - I think it'd be a big problem if users logged in with the wrong email but couldn't log out. Could we recommend that they clear their browser cache or something?

Regarding #967, agreed that we can follow that up in subsequent conversations.

[GeorgianaElena]

Note for the future ➡️
Possible workarounds for #957 could be #974 and 2i2c-org/default-hub-homepage#8

[choldgraf]

OK, now that #974 is in, I think that we can consider this one resolved! 🎉🎉🎉

There are still some things to keep track of and follow up. Specifically:

• As people start using this, we'll likely need to make focused improvements to our docs or implementation, but we can follow up on that as-needed.
• I'll reach out to the CILogon team to ask them about the potential for partnering with their service. @GeorgianaElena has an issue to track that here: Investigate using CILogon instead of Auth0 #967