JarCastingEureka! Clinical User Service
Georgia Clinical and Translational Science Alliance (Georgia CTSA), Emory University, Atlanta, GA
What does it do?
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:
Version 2.0
Moved OAuth user registration from eurekaclinical-user-webapp to eurekaclinical-user-service.
Version 1.0.1
Removed a beta dependency that was inadvertently included in version 1.0. This has no impact on functionality.
Version 1.0
Initial release.
Build requirements
Runtime requirements
- 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)
REST endpoints
/api/userrequests
Manages user account requests.
Role-based authorization
None
Requires successful authentication
No
UserRequest object
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.
Calls
POST /api/userrequests
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.
PUT /api/userrequests/verify/{code}
Marks the user as verified. The code to specify is provided to the user in an email.
/api/protected/users
Manages created user accounts.
Role-based authorization
Call-dependent
Requires successful authentication
Yes
User object
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.
Calls
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
GET /api/protected/users
Returns an array of all User objects. Requires the admin role.
GET /api/protected/users/{id}
Returns a specified User object by the value of its id property, which is unique. Requires either the researcher role or the admin role.
GET /api/protected/users/me
Returns the User object for the currently authenticated user. Requires either the researcher role or the admin role.
POST /api/protected/users/
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.
PUT /api/protected/users/{id}
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.
POST /api/protected/users/passwordchange
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.
/api/protected/oauthproviders
Retrieves information about available OAuth providers.
Role-based authorization
None
Requires successful authentication
Yes
OAuthProvider object
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.
Calls
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
GET /api/protected/oauthproviders
Returns an array of all OAuthProvider objects.
GET /api/protected/oauthproviders/{id}
Returns a specified OAuthProvider object by the value of its id property, which is unique.
GET /api/protected/oauthproviders/byname/{name}
Returns a specified OAuthProvider object by the value of its name property, which is unique.
/api/protected/logintypes
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.
Role-based authorization
None
Requires successful authentication
Yes
LoginType object
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.
Calls
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
GET /api/protected/logintypes
Returns an array of all LoginType objects.
GET /api/protected/logintypes/{id}
Returns a specified LoginType object by the value of its id property, which is unique.
GET /api/protected/logintypes/byname/{name}
Returns a specified LoginType object by the value of its name property, which is unique.
/api/protected/authenticationmethods
Retrieves information about available authentication methods.
Role-based authorization
None
Requires successful authentication
Yes
AuthenticationMethod object
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.
Calls
All calls use standard names, return values and status codes as specified in the Eureka! Clinical microservice specification
GET /api/protected/authenticationmethods
Returns an array of all AuthenticationMethod objects.
GET /api/protected/authenticationmethods/{id}
Returns a specified AuthenticationMethod object by the value of its id property, which is unique.
GET /api/protected/authenticationmethods/byname/{name}
Returns a specified AuthenticationMethod object by the value of its name property, which is unique.
Building it
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.
Performing system tests
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.
Installation
Database schema creation
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.
Configuration
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.
WAR installation
- 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.
Maven dependency
<dependency>
<groupId>org.eurekaclinical</groupId>
<artifactId>eurekaclinical-user-service</artifactId>
<version>version</version>
</dependency>
Developer documentation
Getting help
Feel free to contact us at [email protected].
