Registration and Login Flows

This page describes the entry points and options that a SAML Service Provider can use to make users login/register at the SWITCH edu-ID service and then return the users to a particular URL afterwards.

The edu-ID service consists of two independent components:

  • the Shibboleth Identity Provider (IdP) authenticates users and issues SAML assertions to SAML Service Providers (SP)
  • the edu-ID "My Account" web application is protected by a SAML Service Provider. It allows users to create and manage their edu-ID account.

As can be seen on the diagram below, there are multiple options how to create an edu-ID account and how to authenticate with an edu-ID account:

Login-Registration-Flow_small

If you just want to get something working, please go to the edu-ID Link Composer where you have a wizards that helps you composing the URLs.

If you are however interested in the technical details, please continue reading.

Authentication and Registration Flows

All URLs below use the production edu-ID services as reference. To apply the described techniques to the test instance, replace eduid.ch with test.eduid.ch and login.eduid.ch with test.login.eduid.ch.

URL Parameters

The following case-sensitive, UTF-8-encoded GET parameters can be used on some pages (see graphic and description on this page):

  • providerId: entityID identifier of SP the user wants to access. Default is null. For backwards compatibility reasons the GET parameter "entityID" is also accepted but changed to "providerId".
  • target: URL to send the user to after registration, but have same hostname like entityID, eduID IDP or the statically defined returnURL of a Custom View. For backwards compatibility reasons the GET parameter "return" is also accepted but changed to "target".
  • token: Random code that is usable only once. Only used in case the edu-ID account is created manually, which requires the email address to be confirmed (with token link) to activate the account.
  • shire: Assertion consumer service of Service Provider
  • mail: E-mail address to prefill in manual registration form
  • givenName: Given name/first name of a user to prefill in manual registration form
  • surname: Surname/last name of a user to prefill in manual registration form

Pages:

The URLs below are for the production instance, just prepend the hostnames with "test." to get the URLs of the edu-ID test instance.

I0 (https://test.login.eduid.ch/idp/profile/SAML2/Redirect/SSO?execution=e1s1 and IdP-initiated URL https://login.eduid.ch/idp/profile/SAML2/Unsolicited/SSO): IdP login page. Sets entityID and target parameters in case user clicks on "Create Account" button URL Parameters (for IdP-iniated login URL):

  • providerId: Required
  • target: Required
  • shire: Required

R0 (https://eduid.ch/web/registration/): Let’s users choose to create an edu-ID account with existing AAI account or manually. Either way, the user is sent to R1, with or without a Shibboleth session
URL Parameters:

  • providerId: Optional
  • target: Optional
  • mail: Optional
  • givenName: Optional
  • surname: Optional

R1 (https://eduid.ch/web/registration/1): Ask the user to provide password, accept terms of use, and to provide name/email (continue with 4a) or confirm the use of his AAI attributes (continue with 4b)
URL Parameters:

  • providerId: Optional
  • target: Optional
  • mail: Optional
  • givenName: Optional
  • surname: Optional

R2 (https://eduid.ch/web/registration/2): If user manually creates account, a message is shown on this page that a verification email was sent to the provided e-mail address

R3 (https://eduid.ch/web/registration/3): Page that shows that the edu-ID account was successfully created. The page then provides options to proceed with login/return to service/modify account details. The options depend on one of the 4 registration cases below.
URL Parameters:

  • token: Required if account is created manually

Links/Redirects:

1a: Link from external page directly to registration method page where user can decide to create an account with existing AAI account or manually. Either way, the user is forwarded via 3a to R1 where he has an authenticated AAI session if the user decided to create an account with an existing AAI account. E.g. via https://eduid.ch/web/registration/?providerId=...&target=
1b: User gets to IdP login page via an IdP-initiated login flow (via https://login.eduid.ch/idp/profile/SAML2/Unsolicited/SSO?providerId=…&target=…)
1c: User gets to IdP login page with an authentication request from an SP (standard AAI login case). SP can set target URL with SessionInitiator, e.g. /Shibboleth.sso/Login?entityID=https%3A%2F%2Feduid.ch%2Fidp%2Fshibboleth&target=…
2a: After authentication, the user is sent back to the SP with an authentication response. SP (configured with SWITCHaai default config) then redirects users to target URL stored in server-side session identified by RelayState information, which is part of authentication request and thus survives browser change.
2b: User decided to create an edu-ID account. Is sent to Registration Method page with providerId parameter of SP
3a: User decided if account is created with existing AAI identity or manually. User could be redirected automatically to one or the other option in case there is a Custom View defined for SP with given providerId and in case this Custom View enforces the use of one method
3b: User could get sent directly to "Registration Step 1" from an external page with optional providerId and target parameters. E.g.
https://eduid.ch/web/registration/1/?providerId=...&target=
4a: If user created account manually, an email verification link is sent to his e-mail address and "Registration Step 2" displays a message to confirm the email address by clicking on the link in that email.
4b: If user created account with existing AAI account, no email confirmation is necessary and the user gets directly to "Registration Step 3"
5a: User clicks on email verification link in the same browser
5b: User clicks on email verification link in a different browser (i.e. mobile phone) than was used to start the process
6a: If user decides to click on "Continue to service", he is redirected back to the IdP login page (where he still should have a session)
6b: If a Custom View was used for SP with given providerId, user might be sent to predefined Return URL for Custom View

Registration Flows:

  • Case 1: Direct registration via a link (no or invalid parameters ): Show button "View Account Details"
  • Case 2: Registration via "Create Account" from IdP (providerId, target): Show buttons "View Account Details" and "Proceed to Resource Login"
  • Case 3: Direct registration with CustomView (providerId, [target]): Show "Proceed to service" button which sends user to target URL of CustomView, which is statically defined in CustomView or provided via optional target parameter in R0 or R1.
  • Case 4: Registration via "Create Account" from IdP and Custom Login (providerId, target): Show "Proceed to service" button which sends user to CustomView URL

Configuration of Registration Applications in Resource Registry

Usually registrations for studies etc. are open to all users. Therefore it makes sense to open access to your registration application for all edu-Id users - private users and users with an affiliation. If your application is only accessible with a SWITCH edu-ID account it shoud be configured in the resource registry as edu-ID only service.

  1. exclude SWITCHaai users
  2. include SWITCH edu-ID users
  3. include explicitly SWITCH edu-ID users without an active affiliation (private users)