Identify the user registration flow

[tschaffter]

This ticket is a continuation of the discussion in #749.

Tasks

• [ ] Document the two main registration methods: 1) with KC UI and 2) via custom API
• [ ] Explore registration workflow with Google SSO.
• [ ] Visualize the different registration methods in a Figma document (Challenge Registry Auth Flow).

Remaining questions

• [ ] How to login with via the REST API when the account has been created with SSO (e.g. Google)?
• [x] Can we trigger password reset from the web client or KC admin adapter?
  • See the two methods described here.
  • See also this comment with a direct link to the doc.
• [ ] Can we enable the user to setup OTP with a built-in app page?
  • This may be complex to implement but possible, see this discussion.

[tschaffter]

Document the two main registration methods: 1) with KC UI and 2) via custom API

There are two methods to develop the registration page:

Method 1: Rely on Keycloak registration page:

• The content of the form can be customized (themes and properties), see this example.
• All the user information are stored via KC.
  • We would use a SQL DB in production environment (I already experimented with this).
  • An API service could then access the user data directly from the SQL DB.
• ⚠️ Limited control over the schema of the user data if everything is stored via KC.
• The link to the registration page are dynamic (go to the KC login page then click on the link register and look at the url).
  • It's easy to get the link in the Angular app (same way we get the link to the login page).
  • There is no static link to KC registration page (same comment for the login page).
  • The KC client can be used to generate a link to the registration page (see docs, search for register(options)). The Angular client may not support this feature.
    • We could create a redirection route in our app (e.g. /register).
    • This is only really useful if we want to manually share the link (in an email or in the docs).
  • A solution is to not advertise the registration page, only the login page.
• Registering via KC takes care of email validation (can this be triggered programmatically if we go with Method 2?).
• KC allows to request the user to agree with custom Terms of Use.

Method 2: Registration via a custom API endpoint

• We have full control over the user registration API endpoint.
  • We define the API endpoint with OpenAPI.
  • We can store the data in a DB of our choice (MariaDB currently); only minimal set of user information are stored in KC DB.
  • Less dependent on the IAM solution adopted (here KC) from an API perspective.
• We have already the code for the registration API endpoint.
• We already have most of the code for the registration page (see legacy app).
• This approach has the greatest flexibility when it comes to designing the registration form.
• Registrations via the UI and programmatic registrations all go through the same REST API endpoint.
  • Do we need to support a (public) registration API endpoint?

Questions

• Q: Can we specify an arbitrary link to a registration page that KC would use on its Login page? A: It does not seem possible and we may not want to do this.
• Q: What about registering with SSO? A: Enabling an SSO provider (e.g. Google) requires to specify a redirection URL upon successful login. For now we could simply redirect to the user profile page of the app. We should also probably redirect to a page that shows the Terms of Use like KC does before finalizing the creation of the user account.
• Q: Can we trigger the sending of the user address validation email with Method 2? A: Yes according to this post but potentially with a few limitations (see same post). See also https://github.com/keycloak/keycloak/issues/9112.
• Q: Can we get the link behind the SSO button on KC login page programmatically? A:

[tschaffter]

Visualize the different registration methods in a Figma document

See Challenge Registry Auth Flow

[tschaffter]

Avoid keycloak default login page and use project login page

KC Login page drawbacks:

• Theme syntax is complex.
• KC inject "magic" code that may break the style of the template.
• Templates may need to be fixed after a KC update.

Also:

• Storing the custom user info (gender, job, etc.) is done by User Attributes (neither pro or con, though less flexibility regarding where/how the data are saved).

Notes

• If we want to have full control over the user data entered during registration (e.g. data types, where the data are saved), the best solution would be to use an app built-in registration page.

[tschaffter]

Added to Backlog