Georgia Clinical and Translational Science Alliance (Georgia CTSA), Emory University, Atlanta, GA
It provides RESTful APIs for users to request an account, manage their profile and change their password. It also provides APIs for an administrator to create accounts.
Latest release:
Moved OAuth user registration from eurekaclinical-user-webapp to eurekaclinical-user-service.
Removed a beta dependency that was inadvertently included in version 1.0. This has no impact on functionality.
Initial release.
- Oracle Java JRE 8
- Tomcat 7
- One of the following relational databases:
- Oracle 11g or greater
- PostgreSQL 9.1 or greater
- H2 1.4.193 or greater (for testing)
Manages user account requests.
None
No
Properties:
id: unique number identifying the request (set by the server on object creation, and required thereafter).username: required username string.firstName: optional first name string.lastName: optional last name string.fullName: optional full name string.email: optional email address string.verifyEmail: the same email address string. Must match the value ofemail.organization: optional organization string.title: optional title.department: optional department.loginType: required unique string indicating the login screen that is requested:INTERNAL: using Eureka! Clinical's login screen.PROVIDER: using a trusted third party provider's login mechanism.
type: required unique string indicating requested authentication method:LOCAL: Eureka! Clinical's authentication mechanism.OAUTH: An OAuth provider.LDAP: An LDAP server.
Requests a user account. The UserRequest object is passed in as the body of the request. Returns the URI of the created UserRequest object. Uses status codes as specified in the Eureka! Clinical microservice specification.
Marks the user as verified. The code to specify is provided to the user in an email.
Manages created user accounts.
Call-dependent
Yes
Properties:
id: unique number identifying the user (set by the server on object creation, and required thereafter).username: required username string.firstName: optional first name string.lastName: optional last name string.fullName: optional full name string.email: optional email address string.organization: optional organization string.title: optional title.department: optional department.loginType: required unique string indicating the login screen that is requested:INTERNAL: using Eureka! Clinical's login screen.PROVIDER: using a trusted third party provider's login mechanism.
type: required unique string indicating requested authentication method:LOCAL: Eureka! Clinical's authentication mechanism.OAUTH: An OAuth provider.LDAP: An LDAP server.
created: required the timestamp string indicating when the account was created.active: required boolean indicating whether the account is active.
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
Returns an array of all User objects. Requires the admin role.
Returns a specified User object by the value of its id property, which is unique. Requires either the researcher role or the admin role.
Returns the User object for the currently authenticated user. Requires either the researcher role or the admin role.
Creates a new user. The User object is passed in as the body of the request. Returns the URI of the created User object. Requires the admin role.
Updates the user object with the specified id. The User object is passed in as the body of the request. Requires either the researcher role or the admin role.
Changes the user's password. Returns nothing. Requires either the researcher role or the admin role. This call is non-standard.
This call requires a different JSON object in the body of the request, a PasswordChangeRequest object. Its properties are:
oldPassword: required old password string.newPassword: required new password string.
Retrieves information about available OAuth providers.
None
Yes
Properties:
id: required unique number identifying the OAuth provider.name: required unique string containing the OAuth provider's name.description: optional string containing a longer description of the OAuth provider.
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
Returns an array of all OAuthProvider objects.
Returns a specified OAuthProvider object by the value of its id property, which is unique.
Returns a specified OAuthProvider object by the value of its name property, which is unique.
Retrieves information about available login types, which include 1) authenticating using Eureka! Clinical's built-in login screen or 2) authenticating with a trusted third party provider like an OAuth provider.
None
Yes
Properties:
id: required unique number identifying the object.name: required unique string containing the login type's name. Allowed values areINTERNAL: Authentication using Eureka! Clinical's built-in login screen.PROVIDER: Authentication using an external provider for login.
description: optional string containing the login type's description.
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
Returns an array of all LoginType objects.
Returns a specified LoginType object by the value of its id property, which is unique.
Returns a specified LoginType object by the value of its name property, which is unique.
Retrieves information about available authentication methods.
None
Yes
Properties:
id: required unique number identifying the object.name: required unique string containing the authentication method's name. Allowed values areLOCAL: Uses Eureka! Clinical's built-in authentication.LDAP: Uses an LDAP server.OAUTH: Uses OAuth.
- description: optional string containing the authentication method's description.
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
Returns an array of all AuthenticationMethod objects.
Returns a specified AuthenticationMethod object by the value of its id property, which is unique.
Returns a specified AuthenticationMethod object by the value of its name property, which is unique.
The project uses the maven build tool. Typically, you build it by invoking mvn clean install at the command line. For simple file changes, not additions or deletions, you can usually use mvn install. See https://github.com/eurekaclinical/dev-wiki/wiki/Building-Eureka!-Clinical-projects for more details.
You can run this project in an embedded tomcat by executing mvn process-resources cargo:run -Ptomcat after you have built it. It will be accessible in your web browser at https://localhost:8443/eurekaclinical-user-service/. Your username will be superuser.
A Liquibase changelog is provided in src/main/resources/dbmigration/ for creating the schema and objects. Liquibase 3.3 or greater is required.
Perform the following steps:
- Create a schema in your database and a user account for accessing that schema.
- Get a JDBC driver for your database and put it the liquibase lib directory.
- Run the following:
./liquibase \
--driver=JDBC_DRIVER_CLASS_NAME \
--classpath=/path/to/jdbcdriver.jar:/path/to/eurekaclinical-user-service.war \
--changeLogFile=dbmigration/changelog-master.xml \
--url="JDBC_CONNECTION_URL" \
--username=DB_USER \
--password=DB_PASS \
update
- Add the following Resource tag to Tomcat's
context.xmlfile:
<Context>
...
<Resource name="jdbc/UserService" auth="Container"
type="javax.sql.DataSource"
driverClassName="JDBC_DRIVER_CLASS_NAME"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
url="JDBC_CONNECTION_URL"
username="DB_USER" password="DB_PASS"
initialSize="3" maxActive="20" maxIdle="3" minIdle="1"
maxWait="-1" validationQuery="SELECT 1" testOnBorrow="true"/>
...
</Context>
The validation query above is suitable for PostgreSQL. For Oracle and H2, use
SELECT 1 FROM DUAL.
This service is configured using a properties file located at /etc/ec-user/application.properties. It supports the following properties:
eurekaclinical.userservice.callbackserver: https://hostname:porteurekaclinical.userservice.url: https://hostname:port/eurekaclinical-user-servicecas.url: https://hostname.of.casserver:port/cas-server
A Tomcat restart is required to detect any changes to the configuration file.
- Stop Tomcat.
- Remove any old copies of the unpacked war from Tomcat's webapps directory.
- Copy the warfile into the tomcat webapps directory, renaming it to remove the version. For example, rename
eurekaclinical-user-webapp-1.0.wartoeurekaclinical-user-webapp.war. - Start Tomcat.
<dependency>
<groupId>org.eurekaclinical</groupId>
<artifactId>eurekaclinical-user-service</artifactId>
<version>version</version>
</dependency>
Feel free to contact us at [email protected].