CILogon#
CILogon is a service provider that allows users to login against various identity providers, including campus identity providers. 2i2c can manage CILogon using the JupyterHub CILogonOAuthenticator.
Some key terms about CILogon authentication worth mentioning:
- Identity Provider
The authentication service available through the CILogon connection.
When a user logs in via CILogon, they are first presented with a list of various institutions and organizations that they may choose from (e.g.
UC Berkeley
orAustralia National University
).The available identity providers are members of InCommon, a federation of universities and other organizations that provide single sign-on access to various resources.
Example:
A list of Identity Providers the user may select from.#
- User account
Within an institution, each user is expected to have their own user account (e.g.
myname@berkeley.edu
). This is the account that is used to give somebody an ID on their JupyterHub. This is entered on an Identity Provider’s login screen. For example:The Berkeley authentication screen.#
Note
The JupyterHub usernames will be the email address that users provide when authenticating with an institutional identity provider. It will not be the CILogon
user_id
! This is because theUSERNAME_KEY
used for the CILogon login is the email address.
JupyterHub CILogonOAuthenticator#
The steps to enable the JupyterHub CILogonOAuthenticator for a hub are similar with the ones for enabling GitHubOAuthenticator:
Create a CILogon OAuth client This can be achieved by using the
deployer cilogon-client-create
command.The command needs to be passed the cluster and hub name for which a client id and secret will be generated, but also the hub type, and the authorization callback URL.
The hub domain, as specified in
cluster.yaml
(ex: staging.2i2c.cloud).Example script invocation that creates a CILogon OAuth client for the 2i2c dask-staging hub:
deployer cilogon-client-create 2i2c dask-staging daskhub dask-staging.2i2c.cloud
If successful, the script will have created a secret values file under
config/clusters/<cluster_name>/enc-<hub_name>.secret.values.yaml
. This file holds the encrypted OAuth client id and secret that have been created for this hub.The unencrypted file contents should look like this:
jupyterhub: hub: config: CILogonOAuthenticator: client_id: CLIENT_ID client_secret: CLIENT_SECRET
If not already present, add the secret hub config file to the list of helm chart values file in
config/clusters/<cluster_name>/cluster.yaml
. If you created theenc-<hub_name>.secret.values.yaml
file in step 2, add it the thecluster.yaml
file like so:... hubs: - name: <hub_name> ... helm_chart_values_files: - <hub_name>.values.yaml - enc-<hub_name>.secret.values.yaml ...
Edit the non-secret config under
config/clusters/<cluster_name>/<hub_name>.values.yaml
.3.1. A few rules of thumb when using this method of authentication:
The
admin_users
list need to matchallowed_idps
rules too.It is recommended to define in the
allowed_idps
dict, all the identity providers we plan to allow to be used for a hub. This way, only these will be allowed to be used.Note
The keys allowed in the
allowed_idps
dict must be valid CILogonEntityIDs
. Go to https://cilogon.org/idplist for the list of EntityIDs of each IdP.All the identity providers must define a
username_derivation
scheme, with their ownusername_claim
, that the user cannot change. If they can, it can be easily used to impersonate others! For example, if we allow both GitHub andutoronto.ca
as allowed authentication providers, and only useemail
asusername_claim
, for both providers, any GitHub user can set their email field in their GitHub profile to autoronto.ca
email and thus gain access to anyutoronto.ca
user’s server! So a very careful choice needs to be made here.Note
You can check the CILogon scopes section to checkout available values for
username_claim
. This cannot be changed afterwards without manual migration of user names, so choose this carefully.
3.2. Most common configurations for 2i2c clusters:
Only display specific identity provider as a login options
This example uses GitHub as the only identity provider to show to the user.
jupyterhub: hub: config: JupyterHub: authenticator_class: cilogon CILogonOAuthenticator: # This config option will only display GitHub as the only identity provider option shown_idps: - https://github.com/login/oauth/authorize
Authenticate using Google with CILogon, allowing only a certain domain:
This example sets
2i2c.org
as the only domain that can login into the hub using Googlejupyterhub: hub: config: JupyterHub: authenticator_class: cilogon CILogonOAuthenticator: oauth_callback_url: https://{{ HUB_DOMAIN }}/hub/oauth_callback allowed_idps: http://google.com/accounts/o8/id: username_derivation: username_claim: "email" allowed_domains: - "2i2c.org"
Authenticate using GitHub with CILogon:
This example sets the GitHub nickname as the Hub username using the
username_claim
optionjupyterhub: hub: config: JupyterHub: authenticator_class: cilogon CILogonOAuthenticator: scope: - "profile" oauth_callback_url: https://{{ HUB_DOMAIN }}/hub/oauth_callback shown_idps: - http://github.com/login/oauth/authorize allowed_idps: http://github.com/login/oauth/authorize: username_derivation: username_claim: "preferred_username"
Authenticate using an institutional identity provider for the hub community users and Google for 2i2c staff.
This example:
only shows Shibboleth, the ANU identity provider, and Google as the possible login options through CILogon
sets
2i2c.org
as the only domain that can login to the hub using Googlesets
anu.edu.au
as the only domain that can login to the hub using Shibbolethadds a
2i2c:
prefix to the usernames logging in through Google. The hub usernames are theemail
addresses of these accounts, as specified throughusername_claim
.strips the
@anu.edu.au
domain from the usernames logging in through Shibboleth. The hub usernames are theemail
addresses of these accounts, as specified throughusername_claim
.
Note
To get the value of the key that must go in the
allowed_idp
dict for a specific IdP, go to https://cilogon.org/idplist and get the value of theEntityID
key of the desired institutional IdP.Example config:
jupyterhub: hub: config: JupyterHub: authenticator_class: cilogon CILogonOAuthenticator: oauth_callback_url: https://{{ HUB_DOMAIN }}/hub/oauth_callback admin_users: - admin@anu.edu.au # Only show the option to login with Google and Shibboleth shown_idps: - https://idp2.anu.edu.au/idp/shibboleth - http://google.com/accounts/o8/id allowed_idps: http://google.com/accounts/o8/id: username_derivation: username_claim: "email" action: "prefix" prefix: "2i2c" allowed_domains: - "2i2c.org" https://idp2.anu.edu.au/idp/shibboleth: username_derivation: username_claim: "email" action: "strip_idp_domain", domain: "anu.edu.au" allowed_domains: - "anu.edu.au"
Note
To learn about all the possible config options of the
CILogonOAuthenticator
dict, checkout the docs.Run the deployer as normal to apply the config.
Switch Identity Providers or user accounts#
By default, logging in with a particular user account will persist your credentials in future sessions. This means that you’ll automatically re-use the same institutional and user account when you access the hub’s home page.
Switch Identity Providers#
Logout of the Hub using the logout button or by going to
https://{hub-name}/hub/logout
.Clear browser cookies (optional). If the user asked CILogon to re-use the same Identity Provider connection when they logged in, they’ll need to clear browser cookies for https://cilogon.org.
The dialog box that allows you to re-use the same Identity Provider.#
Firefox example:
An example of clearing cookies with Firefox.#
The next time the user goes to the hub’s landing page, they’ll be asked to re-authenticate and will be presented with the list of available Identity Providers after choosing the CILogon connection.
They can now choose another Identity Provider via CILogon.
Note
If the user choses the same Identity Provider, then they will be automatically logged in with the same user account they’ve used before. To change the user account, see Switch user account.
Switch user account#
Logout of the Hub using the logout button or by going to
https://{hub-name}/hub/logout
.Logout of CILogon by going to the CILogon logout page.
The next time the user goes to the hub’s landing page, they’ll be asked to re-authenticate and will be presented with the list of available Identity Providers after choosing the CILogon connection.
Choose the same Identity Provider to login.
The user can now choose another user account to login with.