External login with dynamic redirection

[byewokko]

solves #316

Summary

• It is possible to specify a redirect URI at the start of the external login process, where the user is redirected after login success or failure.
• The entry point for login can also be used for signup.

Breaking changes

• External login endpoints changed.
• Callback URL changed: there is now a single one for all external providers and methods. You need to change this URL in your client's/app's configuration at your external login provider.
• External login collection fields changed (t -> type, s -> sub, e -> email). There is backward compatibility implemented for the old fields.

Tech details

• Authorization state variable is preserved in the database until external authorization flow completes.
• Module refactored to be more self-contained.
• Handler separated into public, account and admin.

Configuration

• [seacatauth:external_login] default_redirect_uri specifies where to redirect the user when there is no redirect_uri at the external login entry request. Defaults to Seacat Auth WebUI "My account" page.

API

Public

Entry point for login with external account

• GET /public/ext-login/{provider_type}/login?redirect_uri={redirect_uri}
• Initialize logging in with external account. Can also be used as entrypoint for sign-up.
• Navigable, responds with redirect to the external provider OAuth authorization endpoint.
• When the external account is unknown and sign-up is enabled, Seacat Auth attempts to sign up

Entry point for signing up with external account

• GET /public/ext-login/{provider_type}/signup?redirect_uri={redirect_uri}
• Initialize new user sign-up in with external account.
• Navigable, responds with redirect to the external provider OAuth authorization endpoint.

Entry point for pairing an external account with my credentials

• GET /public/ext-login/{provider_type}/pair?redirect_uri={redirect_uri}
• Initialize adding an external login account to my credentials.
• Requires the user to have an active SSO session.
• Navigable, responds with redirect to the external provider OAuth authorization endpoint.

Authorization callback endpoint

• GET /public/ext-login/callback
• Callback from external OAuth authorization (common for all operations and providers).
• Retrieves external user info and completes the requested operation (login, sign-up or pairing account).
• Navigable, responds with redirect to the initially specified redirect URI (or falls back to the configured default_redirect_uri) and adds ext_login_result parameter to the query.
• If the flow fails at any point, the user is also redirected to the requested URI with ext_login_result parameter with error value added to the URL query.
• Defined ext_login_result values
  • login_success: User logged in successfully with external account.
  • signup_success: User was signed up and logged in successfully with external account.
  • pairing_success: External account successfully paired with current user's credentials.
  • login_error: Logging in with external account failed.
  • signup_error: Signing up with external account failed.
  • pairing_error: Pairing external account to current user's credentials failed.

Account

List my external login accounts

• GET /account/ext-login
• List all my external login accounts.

Get my external login account by provider and subject ID

• GET /account/ext-login/{provider_type}/{subject_id}
• Find my external login account by provider type and subject ID.

Remove (unpair) my external login account by provider and subject ID

• DELETE /account/ext-login/{provider_type}/{subject_id}
• Remove my external login account by provider type and subject ID.

Admin

List external login accounts

• GET /admin/ext-login/{credentials_id}
• List all external login accounts registered for specified credentials ID.

Get an external login account by provider and subject ID

• GET /admin/ext-login/{provider_type}/{subject_id}
• Find external login account by provider type and subject ID.

Remove (unpair) an external login account by provider and subject ID

• DELETE /admin/ext-login/{provider_type}/{subject_id}
• Remove external login account by provider type and subject ID.