Users Module
The users
module manages the creation, update, removal and authentication
of users in an application. The module provides the foundations for user
management in a web application.
A user can register himself by using a subscription form. In that case, a verification mail is sent and the user has to follow the verification link defined in the mail to finish the registration process. The user will authenticate using a password.
A user can also use an OAuth/OpenID account and be automatically authenticated and registered to the application. By using an external authentication server, passwords are not stored in the application.
A user can have one or several permissions that allow to protect the
application data. User permissions are managed by the Permissions.Module
.
Integration
The User_Module
manages the creation, update, removal of users
in an application. It provides operations that are used by the user
beans or other services to create and update wiki pages.
An instance of the User_Module
must be declared and registered in the
AWA application. The module instance can be defined as follows:
type Application is new AWA.Applications.Application with record
User_Module : aliased AWA.Users.Modules.User_Module;
end record;
And registered in the Initialize_Modules
procedure by using:
Register (App => App.Self.all'Access,
Name => AWA.Users.Modules.NAME,
Module => App.User_Module'Access);
OAuth Authentication Flow
The OAuth/OpenID authentication flow is implemented by using two servlets
that participate in the authentication. A first servlet will start
the OAuth/OpenID authentication by building the request that the user
must use to authenticate through the OAuth/OpenID authorization server.
This servlet is implemented by the AWA.Users.Servlets.Request_Auth_Servlet
type. The servlet will respond to an HTTP GET
request and it will
redirect the user to the authorization server.
The user will be authenticated by the OAuth/OpenID authorization server
and when s/he grants the application to access his or her account,
a redirection is made to the second servlet. The second servlet
is implemented by AWA.Users.Servlets.Verify_Auth_Servlet
. It is used
to validate the authentication result by checking its validity with
the OAuth/OpenID authorization endpoint. During this step, we can
retrieve some minimal information that uniquely identifies the user
such as a unique identifier that is specific to the OAuth/OpenID
authorization server. It is also possible to retrieve the
user's name and email address.
These two servlets are provided by the User_Module
and they are
registered under the openid-auth
name for the first step and
under the openid-verify
name for the second step.
Configuration
The users module uses a set of configuration properties to configure the OpenID integration.
Name | Description |
---|---|
users.server_id | The server id when several instances are used. |
1 | |
users.auth_key | An authentication key used to sign the authentication cookies. |
8ef60aad66977c68b12f4f8acab5a4e00a77f6e8 | |
users.allow_register | Allow users to register themselves on the server. When disabled, users can be created by the AWA 'user' command. |
#{app_login_register} | |
openid.realm | The REALM URL used by OpenID providers to verify the validity of the verification callback. |
#{app_url_base}/auth | |
openid.callback_url | The verification callback URI used by the OpenID provider to redirect the user after authentication. |
#{app_url_base}/auth/verify | |
openid.success_url | The URI where the user is redirected after a successful authentication. |
#{contextPath}/workspaces/main.html | |
openid.error_url | The URI where the user is redirected when some authenticate error occurred. |
#{contextPath}/auth/login.html | |
auth.url.orange | Orange OpenID access point |
https://openid.orange.fr | |
auth.provider.orange | Auth provider to use for Orange |
openid | |
auth.url.yahoo | Yahoo! OpenID access point |
https://api.login.yahoo.com/oauth2/request_auth | |
auth.provider.yahoo | Auth provider to use for Yahoo! |
yahoo | |
auth.url.google | Google OpenID access point |
https://www.google.com/accounts/o8/id | |
auth.provider.google | Auth provider to use for Google |
openid | |
auth.url.github | GitHub OAuth2 Connect access point |
https://github.com/login/oauth/authorize | |
auth.provider.github | Auth provider to use for GitHub |
github | |
github.request_url | GitHub OAuth token access point |
https://github.com/login/oauth/access_token | |
github.scope | GitHub OAuth scope |
read:user, read:email | |
github.callback_url | GitHub verify callback |
#{app_oauth_url_base}#{contextPath}/auth/verify | |
github.issuer | GitHub issuer identification |
https://github.com | |
auth.url.gitlab | GitLab OAuth2 Connect access point |
https://gitlab.com/oauth/authorize | |
auth.provider.gitlab | Auth provider to use for GitLab |
yahoo | |
gitlab.request_url | Gitlab OAuth token access point |
https://gitlab.com/oauth/token | |
gitlab.scope | Gitlab OAuth scope |
openid email | |
gitlab.callback_url | Gitlab verify callback |
#{app_oauth_url_base}#{contextPath}/auth/verify | |
gitlab.issuer | Gitlab issuer identification |
https://gitlab.com | |
auth.url.twitter | Twitter OAuth2 Connect access point |
https://api.twitter.com/oauth/authenticate | |
auth.provider.twitter | Auth provider to use for Twitter |
yahoo | |
auth.url.facebook | Facebook OAuth access point |
https://www.facebook.com/dialog/oauth | |
auth.provider.facebook | Auth provider to use for Facebook |
facebook.callback_url | Facebook verify callback |
#{app_oauth_url_base}#{contextPath}/auth/verify | |
facebook.request_url | Facebook request OAuth token access point |
https://graph.facebook.com/oauth/access_token | |
facebook.scope | Facebook permission scope |
public_profile,email | |
facebook.client_id | Facebook API client ID |
#{app_facebook_client_id} | |
facebook.secret | Facebook API secret |
#{app_facebook_secret} | |
auth.url.google-plus | Google+ OAuth access point |
https://accounts.google.com/o/oauth2/auth | |
auth.provider.google-plus | Auth provider to use for Google+ |
google-plus | |
google-plus.issuer | Google+ issuer identification |
accounts.google.com | |
google-plus.callback_url | Google+ verify callback |
#{app_oauth_url_base}#{contextPath}/auth/verify | |
google-plus.request_url | Google+ request OAuth token access point |
https://accounts.google.com/o/oauth2/token | |
google-plus.scope | Google+ permission scope |
openid profile email | |
google-plus.client_id | Google+ API client ID |
#{app_google_plus_client_id} | |
google-plus.secret | Google+ API secret |
#{app_google_plus_secret} | |
auth-filter.redirect | URI to redirect to the login page |
#{contextPath}/auth/login.html | |
verify-access-key.redirect | URI to redirect to the login page |
#{contextPath}/auth/login.html | |
verify-access-key.change-password | URI to redirect to the change password page when the access key is verified, the user account is registered but there is no password for authentication |
#{contextPath}/auth/change-password/ | |
app_login_register | Enable or disable user registration through the web interface |
#{not empty app_login_register ? app_login_register : true} | |
app_login_email | Enable or disable user login through the email/password form |
#{not empty app_login_email ? app_login_email : true} | |
app_login_openid | Enable or disable user login through OpenID/OAuth2 |
#{not empty app_login_openid ? app_login_openid : true} | |
app_login_methods | List of login methods which are enabled for authentication |
#{not empty app_login_methods ? app_login_methods : 'email,google,facebook'} |
Ada Beans
Several bean types are provided to represent and manage the users. The user module registers the bean constructors when it is initialized. To use them, one must declare a bean definition in the application XML configuration.
Name | Description |
---|---|
login | This bean is used by the login form |
register | This bean is used by the registration form |
resetPassword | This bean is used by the reset password form |
lostPassword | This bean is used by the lost password form |
logout | This bean is used by the logout process |
user | This bean allows to provide information about the current logged user. |