{"id":18407223,"url":"https://github.com/octri/authentication-lib","last_synced_at":"2025-04-12T20:59:07.605Z","repository":{"id":258715487,"uuid":"867280970","full_name":"OCTRI/authentication-lib","owner":"OCTRI","description":"Simple and reusable user and role management with Spring Security","archived":false,"fork":false,"pushed_at":"2024-12-20T20:06:50.000Z","size":865,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-12T20:59:03.520Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OCTRI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-03T19:09:35.000Z","updated_at":"2024-12-20T20:06:53.000Z","dependencies_parsed_at":"2024-12-20T19:28:26.234Z","dependency_job_id":"10bd1179-8e1d-4f00-953b-d574c2022ff1","html_url":"https://github.com/OCTRI/authentication-lib","commit_stats":null,"previous_names":["octri/authentication-lib"],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Fauthentication-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Fauthentication-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Fauthentication-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Fauthentication-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OCTRI","download_url":"https://codeload.github.com/OCTRI/authentication-lib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631703,"owners_count":21136561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T03:13:06.302Z","updated_at":"2025-04-12T20:59:07.583Z","avatar_url":"https://github.com/OCTRI.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OCTRI Authentication Library\n\nThis library allows you to use the entities, services, and templates provided to bootstrap authentication into a new Spring Boot application. Domain classes for users and roles are provided along with Flyway migrations to initialize a MySQL database. Once configured, your application will have endpoints and UI for login and user management. In addition, failure and success handlers are provided that will persist all login attempts with IP addresses for auditing purposes and lock an account after a configurable number of failed login attempts.\n\n## Simple Setup\n\nThe simplest way of using the library is to generate your project using [OCTRI's Spring Boot archetype](https://source.ohsu.edu/OCTRI-Apps/spring-boot-archetype). Enable the library using the `useAuth` flag.\n\n```\nmvn archetype:generate \\\n\t-DinteractiveMode=false \\\n\t-DarchetypeGroupId=org.octri \\\n\t-DarchetypeArtifactId=spring-boot-archetype \\\n\t-DarchetypeVersion=\u003ccurrent archetype version\u003e \\\n\t-DarchetypeCatalog=local \\\n\t-DgroupId=org.octri \\\n\t-DartifactId=sample \\\n\t-Dversion=0.0.1-SNAPSHOT \\\n\t-Dpackage=org.octri.sample \\\n\t-DprojectName='Sample Project' \\\n\t-DuseAuth=true\n```\n\nThis will generate a Spring Boot application with all of the dependencies, database migrations, Mustache templates, and other files needed to integrate the library.\n\n## Manual Setup\n\nThe following sections describe how to manually integrate the authentication library into a Spring Boot application. The [auth-example-project repository](https://source.ohsu.edu/OCTRI-Apps/auth-example-project) contains a minimal web application that you can use as a guide.\n\n### Dependencies\n\nAdd the library's packages to the depdencies in your application's `pom.xml` file. All applications should add the `authentication_lib` core package.\n\n```xml\n\t\u003cdependency\u003e\n\t\t\u003cgroupId\u003eorg.octri.authentication\u003c/groupId\u003e\n\t\t\u003cartifactId\u003eauthentication_lib\u003c/artifactId\u003e\n\t\t\u003cversion\u003e${authentication_lib.version}\u003c/version\u003e\n\t\u003c/dependency\u003e\n\t\u003cdependency\u003e\n\t\t\u003cgroupId\u003eorg.octri.authentication\u003c/groupId\u003e\n\t\t\u003cartifactId\u003eauthentication_ui_bootstrap5\u003c/artifactId\u003e\n\t\t\u003cversion\u003e${authentication_lib.version}\u003c/version\u003e\n\t\u003c/dependency\u003e\n```\n\n### Flyway Migrations\n\nTo create the database tables used by the library, copy the SQL migrations from `setup/migrations/` into your project's Flyway migration directory (`src/main/resources/db/migration/`). If you used the OCTRI Spring Boot archetype to generate your application and enabled the library, this has already been done for you. If adding the library to an existing application, you will need to rename the migrations so that they are applied after existing migrations.\n\n\u003e Note: Prior to version 0.5.0, migrations were automatically applied by Flyway. This could cause issues with migration ordering and complicated adding the library to existing applications, so the migrations must now be manually included in projects.\n\nAdditional migrations are provided to enable specific workflows. See the [setup README](setup/README.md) and files in `setup/optional_migrations` for details.\n\n### Package Scanning\n\nThe library will transitively bring in several Spring Boot jars along with MySQL, etc. In your Application definition, the Spring Boot Runner needs to set some additional parameters to ensure that domain, repositories, and autowired components for the Authentication Library are picked up. You will also likely need to include your project's package in these annotations.\n\n```java\n@SpringBootApplication\n@ComponentScan({\"org.octri.test\", \"org.octri.authentication\"})\n@EntityScan( basePackages = {\"org.octri.test\", \"org.octri.authentication\"} )\n@EnableJpaRepositories(\"org.octri.authentication\")\npublic class TestProjectApplication {\n\n\tpublic static void main(String[] args) {\n\t\tSpringApplication.run(TestProjectApplication.class, args);\n\t}\n}\n```\n\nThe authentication library provides security configuration options for a web-based application [`FormSecurityConfiguration.java`](./authentication_lib/src/main/java/org/octri/authentication/FormSecurityConfiguration.java) or a REST application [`ApiSecurityConfiguration.java`](./authentication_lib/src/main/java/org/octri/authentication/ApiSecurityConfiguration.java). Either can be enabled by simply extending the configuration you want to use and adding the `@Configuration` annotation:\n\n```java\n@Configuration\npublic class SecurityConfiguration extends FormSecurityConfiguration {\n\n}\n```\n\nThe example project has a few other pieces of configuration, including a sample landing page `home.html` and a controller to handle request mappings. These are not strictly necessary.\n\n### Configuration\n\nConfigure the Spring Datasource in your Boot application. [https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-sql.html]. You can use a mix of table-based, LDAP, and SAML authentication, and several properties are exposed for customization of your app. All application configuration can be set through properties or environment variables documented on [this page](docs/CONFIGURATION_PROPERTIES.md).\n\nIf using the standard Docker/MySQL setup, start the MySQL container first to create the database and user. Then start up your application and Flyway migrations for the authentication library should create some structure for users and roles.\n\n### JavaScript\n\n`authlib.js` the application context path to generate valid URLs for links. To provide the application context add the following meta tag to your pages. The trailing slash is required.\n\n```html\n\u003cmeta name=\"ctx\" content=\"{{req.contextPath}}/\" /\u003e\n```\n\n### Session Timeout and Cookie Settings\n\nSession timeout and session cookie properties are managed by the properties shown below. See the [full list of properties](https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html). Also see [OHSU's guidelines](http://ozone.ohsu.edu/cc/sec/isp/00005.pdf).\n\nTo override any of these values set the corresponding environment variable (e.g. `server.servlet.session.timeout` becomes `SERVER_SERVLET_SESSION_TIMEOUT`), or define them in your own `application.properties` file. The order in which external configuration is loaded may be found [here](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html).\n\n```\n# Session timeout in minutes\nserver.servlet.session.timeout=20m\n\n# Set to true to restrict the session cookie to HTTPS\nserver.servlet.session.cookie.secure=true\n\n# Set to true to prevent JavaScript from accessing the session cookie; it will still be\n# sent with same-origin Ajax requests\nserver.servlet.session.cookie.http-only=true\n\n# Set to \"strict\" to prevent sending the session cookie with cross-origin requests; set to\n# \"none\" to allow the cookie to be sent with cross-origin requests\nserver.servlet.session.cookie.same-site=strict\n```\n\nThe cookie settings shown above are a secure starting point, and they should only rarely need to be changed.\n\n### Password Requirements\n\nPasswords are validated by the `PasswordConstraintValidator.java` and the `UserController#changePassword()` `POST` method. They follow OHSU password standards. See `ValidPassword.java`.\n\nUsers and System Administrators shall employ the following minimum password attributes:\n\n* 8 character minimum\n* Inclusion of all of the following elements:\n  * An alpha character (e.g., zyxwvut);\n  * A numeric character (e.g., 12345);\n  * A capitalized letter or punctuation or non-alphanumeric character (e.g., !@#*+)\n  * An initial or temporary password that will expire following the first successful login to an account;\n  * An account lockout mechanism that is triggered after seven (7) unsuccessful account login attempts (TODO: within thirty (30) minutes).\n  * Avoid words found in any dictionary (including medical, foreign language) (TODO: provide more words)\n  * Shall not contain the user login-name (UserID).\n\n### User Roles\n\nThe library sets up roles USER, ADMIN, and SUPER. The [`UserController`](./authentication_lib/src/main/java/org/octri/authentication/controller/UserController.java) restricts user management to the admin and super roles, and users cannot edit themselves.\n\n#### Add Roles and Users\n\nFor default OCTRI users see the [auth_default_users](https://source.ohsu.edu/OCTRI-Apps/auth-default-users) project. It provides scripts for creating roles and users.\n\nThe authentication_lib provides the default roles via Flyway. Those roles are: `ROLE_USER`, `ROLE_ADMIN`, and `ROLE_SUPER`.\n\nIf you want roles and users other than what's in the auth_default_users project follow this process to add roles, and users with roles.\n\n```sql\n-- Add a role\nINSERT INTO user_role (id, description, role_name)\nVALUES (4, 'Manager', 'ROLE_MANAGER');\n\n-- Add a user\nINSERT INTO user (account_expiration_date, account_expired, account_locked,\n\t\t\t\t  consecutive_login_failures, credentials_expiration_date,\n\t\t\t\t  credentials_expired, email, enabled, first_name, institution, last_name,\n\t\t\t\t  password, username)\nVALUES\n\t(NULL, 0, 0, 0, NULL, 0, 'foobar@example.com', 1, 'Foo', 'OHSU', 'Bar', NULL, 'foobar');\nSET @user_id = (SELECT last_insert_id());\n\n-- Link the role and user\nINSERT INTO user_user_role (user, user_role)\nVALUES\n\t(@user_id, 4);\n```\n\nIf adding a table-based user, you can add an empty or bogus password through SQL and then use the forgot password functionality to get a legitimate hashed password.\n\n### Web Application Authentication and UI\n\nAuthentication flow uses fairly standard redirection and provides success and failure handlers to record login attempts and lock accounts after consecutive failures. You may also override the default public routes.\n\nThe following methods are provided by the [`BaseSecurityConfiguration`](./authentication_lib/src/main/java/org/octri/authentication/BaseSecurityConfiguration.java) and can be overridden by the application's security configuration:\n\n* `defaultSuccessUrl()` - Where to redirect after successful login. By default `/admin/user/list`.\n* `loginFailureRedirectUrl()` - Where to redirect after failed login. By default `/login?error`\n* `logoutUrl()` - The request mapping for logout. By default `/logout`.\n* `logoutSuccessUrl()` - Where to redirect after successful logout. By default `/login`.\n* `customPublicRoutes()` - Include additional public routes. The default set may be found in the string array: `BaseSecurityConfiguration.DEFAULT_PUBLIC_ROUTES`\n\nFor UI, the library provides a login page and navigation bar with links to \"Home\", User Administration pages, and logout. Review and run the auth_example_project for this most basic setup. User Administration pages are also available as fragments so your application can provide its own navigation or layout. Your application can override any views or request mappings by adding your own versions to your project. For example, if you want your own login page, create `login.html` in the `src/main/resources/templates` directory.\n\n#### Webjars (CSS and JavaScript dependencies)\n\nThe authentication library uses Bootstrap, Font Awesome, jQuery, jQuery-UI, and DataTables libraries for styling and functionality. These are included as resources through webjars in the `pom.xml` file. The library also uses the webjars-locator dependency to manage versions of the webjars so that your application doesn't have to. To keep in sync with the authentication library, it is recommended that you do not include your own dependencies of these jars but rely on the library to keep them up to date. You can refer to any of the assets provided by the authentication library in your application code. Here is what is included:\n\nCSS is located in the `authlib_fragments/css.mustache` template. By default it includes the following files:\n\n```html\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{req.contextPath}}/webjars/bootstrap/css/bootstrap.min.css\" /\u003e\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{req.contextPath}}/webjars/font-awesome/css/all.min.css\" /\u003e\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{req.contextPath}}/assets/css/authlib.css\" /\u003e\n```\n\nIf you provide the `formView` model property it will also include:\n\n```html\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{req.contextPath}}/webjars/jquery-ui/jquery-ui.min.css\" /\u003e\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{req.contextPath}}/webjars/jquery-ui/jquery-ui.theme.min.css\" /\u003e\n```\n\nIf you provide the `listView` model property it will include:\n\n```html\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{req.contextPath}}/webjars/datatables/css/dataTables.bootstrap5.min.css\" /\u003e\n```\n\nLikewise, JavaScript is included in the `authlib_fragments/assets.mustache` template. By default it includes the following:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"{{req.contextPath}}/webjars/jquery/jquery.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"{{req.contextPath}}/webjars/bootstrap/js/bootstrap.bundle.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"{{req.contextPath}}/assets/js/authlib.js\"\u003e\u003c/script\u003e\n```\n\nSimilar to `css.mustache`, if you pass the `formView` model property it will include the corresponding JavaScript:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"{{req.contextPath}}/webjars/jquery-ui/jquery-ui.min.js\"\u003e\u003c/script\u003e\n```\n\nAnd if you pass the `listView` model property it will include:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"{{req.contextPath}}/webjars/datatables/js/jquery.dataTables.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"{{req.contextPath}}/webjars/datatables/js/dataTables.bootstrap5.min.js\"\u003e\u003c/script\u003e\n```\n\nAgain, the exact DataTables JavaScript used will depend on your selection of UI package.\n\nIf your application has its own navigation and is using the User Management fragments instead of the templates, you will need to make sure the css and js are loaded properly. You can assume that all pages will need jQuery and Bootstrap. Other dependencies may not be needed on every page, but the New and Edit User forms, for example, need jQuery UI to show calendar popups and the User list page will need DataTables. The `UserController.java` is responsible for setting the `formView` and `listView` model properties for User Management.\n\n### API Authentication\n\nThis functionality has not yet been tested or used in an example project, but should provide JSON responses to authentication requests.\n\n## How to use Mustache fragments in your application\n\nThe authentication library provides these pages: `admin/user/form.mustache`, `admin/user/list.mustache`, `error.mustache`, `login.mustache`, `user/password/change.mustache`, `user/password/forgot.mustache`, and `user/password/reset.mustache`. You'll likely need to implement these in your own project if you use a custom layout and navbar.\n\nSee above in the \"Webjars\" section for how to include the required CSS and JavaScript. For all pages assume Bootstrap, Font Awesome, and jQuery 3 are required.\n\nCreate `mustache-templates/login.mustache` and in the body include the fragment: `{{\u003eauthlib_fragments/login}}`.\n\nCreate `mustache-templates/error.mustache` and in the body include the following HTML. The `UserController` will populate the model properties.\n\n```html\n\u003cdiv class=\"container-fluid\"\u003e\n\t\u003cdiv class=\"alert alert-danger\"\u003e\n\t\t\u003cp\u003eError {{status}}: {{error}} ({{message}})\u003c/p\u003e\n\t\t\u003cp\u003e{{timestamp}}\u003c/p\u003e\n\t\u003c/div\u003e\n\u003c/div\u003e\n```\n\nCreate `mustache-templates/admin/user/form.mustache` and in the body include the fragment: `{{\u003eauthlib_fragments/admin/user/form}}`. This is the **New User** form - link to `{{contextPath}}/admin/user/form`. You can include the required JavaScript by using the fragment `{{\u003eauthlib_fragments/assets}}`. Include the required CSS by using the fragment `{{\u003eauthlib_fragments/css}}`.\n\nCreate `mustache-templates/admin/user/list.mustache` and in the body include the fragment: `{{\u003eauthlib_fragments/admin/user/list}}`. This is the **List of Users** page - link to `{{contextPath}}/admin/user/list`. You can include the required JavaScript by using the fragment `{{\u003eauthlib_fragments/assets}}`. Include the required CSS by using the fragment `{{\u003eauthlib_fragments/css}}`.\n\n**If you want table-based authentication then you need to create three more templates.**\n\nCreate `mustache-templates/user/password/change.mustache` and in the body include the fragment: `{{\u003eauthlib_fragments/user/password/change}}`.\n\nCreate `mustache-templates/user/password/forgot.mustache` and in the body include the fragment: `{{\u003eauthlib_fragments/user/password/forgot}}`.\n\nCreate `mustache-templates/user/password/reset.mustache` and in the body include the fragment: `{{\u003eauthlib_fragments/user/password/reset}}`.\n\n## CSRF\n\nAll forms must include a CSRF token. Inside each form include the following fragment: `{{\u003eauthlib_fragments/forms/csrf_input}}`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctri%2Fauthentication-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctri%2Fauthentication-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctri%2Fauthentication-lib/lists"}