OpenID Connect Integration
OpenID Connect can be integrated to Agate in three different ways:
- Agate is an OpenID Connect provider: this is already partly the case, but the implementation needs to be completed (discovery URL, JSON web key set),
- An external OpenID Connect provider can be used to prefill the sign-up form: the claims extracted from the user info object retrieved from the provider can be used to preset the values of the signup fields,
- An external OpenID Connect provider can be used to delegate authentication: identity is verified by redirecting the user to the provider and finally start an OBiBa session in Agate, with an associated user profile.
Integrate with institution's existing ID providers which most likely support OpenID Connect.
Describe simply who is doing what and how to obtain the result.
| # | Who | What | How | Result |
|---|---|---|---|---|
| 1 | administrator | creates a realm based on a OIDC provider | by creating a new realm of type OpenID connect | A new realm is added |
| 2 | user | signup using OIDC | by authenticating in selected OIDC provider | New user profile is filled with information extracted from OIDC user info |
| ... | user | signin with OIDC | by authenticating in selected OIDC provider | User gets authenticated in Agate |
Implementing these features will affect:
- Agate: sign in/sign up web services and pages,
- Mica: sign in page,
- Drupal/Agate module: sign in and sign up pages.
There are number of base functionalities (domain, OpenID Connect processing and servlet filters) that are already available in obiba-oidc. See usage of this library in Opal.
The OIDC providers are to be configured in Agate. These will be persisted in the Mongo database.
The OIDCConfiguration class will handle the provider's configuration. Can be extended as needed, especially for enabling or not the associated realm.
The OIDCConfigurationProvider class is to be implemented (will be the configuration manager service).
For each OIDC configuration registered, there is a Shiro Realm to be added. When a OIDC configuration is removed, the corresponding Shiro realm is to be removed as well (and associated users will be deactivated).
| REST Web Service | Description |
|---|---|
GET /auth/providers |
List the OIDC providers summary, to be used by application clients. |
The web services to be used when managing a OIDC provider configuration are the ones for administrating alternate realms. OIDC configuration is a part of the OIDC-based realm entity.
In Administration section, add OpenID Connect providers management page(s)...
The purpose of this feature is to use OpenID Connect User Info object to prepare the user sign up: the Agate user profile form will be prefilled (most probably there will be missing Agate specific user attributes, thus the form is still to be displayed (or is it a configuration option?)).
Signup filter will be based on OIDCLoginFilter class.
Callback filter will be based on OIDCCallbackFilter class.
| Entry Point | Description |
|---|---|
/auth/signup/<provider>[?redirect=<redirect_url>[&error=<redirect_url>]] |
Sign up using user info extracted from provider. This provider will also be used as the signin realm of the created user |
/auth/callback/<provider>?action=signup |
Handle signup callback (after login has been performed against provider). |
The callback filter will perform the following workflow:
- identify the provider from the callback URL,
- get the provider's configuration (
OICDConfiguration) to start the OpenID Connect dance:- get authorization access token,
- get ID token,
- verify the ID token signature,
- get user info.
- on success:
- find there is no user in Agate with same username/email,
- prepare a Agate user JSON object:
- map the user info's claims to user profile attributes,
- apply the groups defined in the
OIDCConfiguration(+ group mapping if there are provider's ones that are returned?), - associate user to provider's realm.
- prepare the servlet response:
- set the redirect URL (either the one specified on signin entry point or the default one),
- set the user JSON object as a cookie so that the client can prefill the signup form.
- on failure (for any reason, can be during OIDC flow or at Agate's user validation):
- redirect to provided (or default) error URL with a meaningful error message code in the query param.
The signup entry point is accessed from Drupal's or Agate's signup page. The list of provider's is to be retrieved from a Agate public web service (/ws/auth/providers).
When a Sign up with... button is selected, the OIDC danse is started with the selected provider. The purpose of this phase is to prefill the signup form with the information that is retrieved from the User Info object. No user profile is created at this stage. On callback success, the user is redirected to a registration completion page (new page). On submission of the form the user profile will be created, associated to the OIDC provider's realm.
The purpose of this feature is to enable authentication delegation to an OpenID Connect provider. Just like with the other authentication delegates, the user profile MUST exist in Agate (delegated authentication success is not enough). See Sign up with ... section.
Signin filter will be based on OIDCLoginFilter class.
Callback filter will be based on OIDCCallbackFilter class.
| Entry Point | Description |
|---|---|
/auth/signin/<provider>[?redirect=<redirect_url>[&error=<redirect_url>]] |
Redirect user to provider's login form, with callback parameter. Register the final redirect after callback is successful or not. |
/auth/callback/<provider>[?action=signin] |
Handle signin callback (after login has been performed against provider). Signin callback is the default action. |
The callback filter will perform the following workflow:
- identify the provider from the callback URL,
- get the provider's configuration (
OICDConfiguration) to start the OpenID Connect dance:- get authorization access token,
- get ID token,
- verify the ID token signature.
- on success:
- find the corresponding Agate's user,
- check the user is enabled,
- check user realm is the provider's one,
- create a OBiBa session,
- prepare the servlet response:
- set the redirect URL (either the one specified on signin entry point or the default one),
- set the OBiBa session's ticket as a cookie.
- on failure (for any reason, can be during OIDC flow or at Agate's user validation):
- redirect to provided (or default) error URL with a meaningful error message code in the query param.
The signin entry point is accessed from Drupal's or Mica's signin page. The list of provider's is to be retrieved from a Agate public web service (/ws/auth/providers).
Complete API by implementing metadata discovery (simplifies the client configuration) and JSON web keys (enable JWT object signature verification) web services.
The testing will be done with:
- Keycloak
- gluu ?
- ORCID sandbox, see Getting started with your ORCID integration and the ORCID OpenID Connect API documentation,
- GitHub (as some data harmonization work happens on GitHub).
It should also be possible for Opal to connect to Agate as an external OpenID Connect provider. This would allow to test the OpenID Connect API of Agate.
It would be nice to support OAuth access in the R API of OBiBa tools, to avoid username/password usage. This is also an OAuth use case: authorizing application (Opal, Agate, Mica) resources access on behalf of a user to an application (the R script).