Security, Users, and Roles

Overview

Documents the security and user management features.

Details

The security service provides authentication, authorization, and logout services. A user timeout also supported so users do not remained logged in indefinitely. The default timeout is set to 2 hours and can be easily changed. All REST services are secured by the use of an authorization token that is obtained from the security service and passed to other calls.  For a truly secured environment, it is recommended that the system be run under HTTPS instead of HTTP. Otherwise usernames, passwords, and authorization tokens will be passed in plain text with HTTP requests.

When a user authenticates, an authToken (a random UUID) is passed back to the client which can be used on subsequent calls to the server.  This authToken is checked against a map of valid tokens and can be used to identify the user who was assigned this token.   The time of an authentication request is recorded by the authToken so that it can be determined when the last request with this token was made.  If upon checking an authToken the last request was longer ago than the "ihtsdo.security.timeout" setting, then the authorization is rejected and the user is redirected to log in again.

Restarting the server clears all authTokens and users must re-authenticate. The application will redirect users to the login page if their authToken is no longer valid (either because of inactivity timeout or server restart).

For the production IHTSDO deployment, which uses IMS, the sequence of events looks like this:

• If a "user" cookie exists, the application attempts to see if the authorization token is still valid.
  • If valid, the user enters the application where they last left off (based on user preferences)
  • If invalid, the user is sent to IMS with a redirection link.  
  • Upon returning to the application, the user's credentials are checked (by attempting to retrieve user info from IMS using browser cookies).  If this is successful, an authorization token is generated and stored in the user cookie.
  • The user is then logged in and redirected to where they last left off (based on user preferences)
• If a "user" cookie does not exist
  • The user is logged out and only the "directory" is visible.
  • Upon clicking "login" the cycle of events described above occurs.
• Any subsequent call to an application service includes an authToken
  • The application service requests the role of the user using that token (for authorization checks)
  • This internally requests the user using that token which performs a check that the authToken is itself valid and that the date of the last use of the token is not prior to the timeout period from the current time.
    • If either the authToken is not valid or the timeout period has been exceeded, an HTTP 401 error is returned to the client
    • Otherwise, the role is returned to the application
  • The application service then authorizes that role
    • If the role has privileges to access the capability, the request proceeds
    • Otherwise, an HTTP 401 error is returned to the client.
• A period of 2 hours passes without activity on a particular authToken
  • Any requests with this authToken will result in an HTTP 401 error.
• Upon a 401 error, the user is directed back through the authorization scheme described at the top.

User Management

While authentication of users is offloaded to the IHTSDO identity management service, there is some user management within the application itself.    Users can be "created" within the system either manually or by having them log in.  Whenever a user logs in, the local tracking of user data is updated to reflect the current state of IMS.

The user's application role is also determined by IMS via the "refset-users" and "refset-administrators" groups in the IHTSDO crowd deployment.

A user who is not logged into IMS can still access the tool, however they will see only the contents of the directory page.

Authorization

Each REST call not only verifies the authToken is valid but also authorizes the user's role against the task being attempted.  Read-only services generally only require VIEWER role where as things like project creation and refset editing require a USER role.   Any REST service that takes a project or map project id requires a "project role" by that user on that project.  See REST documentation for more details.

User Roles

The system make use of "application roles" and "project roles".  There are 3 application roles:

• VIEWER - the typical role associated with a user, it confers no special privileges
• USER - assigned via belonging to the "refset-users" group.  This role allows users to create projects, refsets, and translations.
• ADMIN - assigned only via belonging to the "refset-administrators" group.  This is a superuser role that can access any application feature.

There are four project roles:

• VIEWER - has read-only access to the directory of public refsets and translations.
• AUTHOR - has the ability to participate in the authoring part of a refset or translation workflow.
• REVIEWER - has the ability to participate in the reviewer part of a refset or translation workflow - and can also serve as an AUTHOR.
• ADMIN - has the ability to see all workflow states of refsets or translations in a project, and can also serve as an AUTHOR or REVIEWER.

Configuration

The following configuration settings affect security.

References/Links

• User Management