{"id":19243476,"url":"https://github.com/bootique/bootique-shiro","last_synced_at":"2025-10-19T06:55:22.898Z","repository":{"id":43583993,"uuid":"68718213","full_name":"bootique/bootique-shiro","owner":"bootique","description":"Provides Apache Shiro integration with Bootique.","archived":false,"fork":false,"pushed_at":"2025-07-12T20:41:07.000Z","size":462,"stargazers_count":4,"open_issues_count":2,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-12T22:22:55.824Z","etag":null,"topics":["bootique","java","security","shiro"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bootique.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2016-09-20T14:07:46.000Z","updated_at":"2025-07-12T20:41:10.000Z","dependencies_parsed_at":"2023-11-22T01:58:22.582Z","dependency_job_id":"25b1775e-c872-4243-82b8-9d71383e826f","html_url":"https://github.com/bootique/bootique-shiro","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/bootique/bootique-shiro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootique%2Fbootique-shiro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootique%2Fbootique-shiro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootique%2Fbootique-shiro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootique%2Fbootique-shiro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bootique","download_url":"https://codeload.github.com/bootique/bootique-shiro/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootique%2Fbootique-shiro/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265658864,"owners_count":23806825,"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":["bootique","java","security","shiro"],"created_at":"2024-11-09T17:18:09.702Z","updated_at":"2025-10-19T06:55:22.755Z","avatar_url":"https://github.com/bootique.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n  Licensed to ObjectStyle LLC under one\n  or more contributor license agreements.  See the NOTICE file\n  distributed with this work for additional information\n  regarding copyright ownership.  The ObjectStyle LLC licenses\n  this file to you under the Apache License, Version 2.0 (the\n  \"License\"); you may not use this file except in compliance\n  with the License.  You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\n  Unless required by applicable law or agreed to in writing,\n  software distributed under the License is distributed on an\n  \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n  KIND, either express or implied.  See the License for the\n  specific language governing permissions and limitations\n  under the License.\n  --\u003e\n\n[![build test deploy](https://github.com/bootique/bootique-shiro/actions/workflows/maven.yml/badge.svg)](https://github.com/bootique/bootique-shiro/actions/workflows/maven.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/io.bootique.shiro/bootique-shiro.svg?colorB=brightgreen)](https://search.maven.org/artifact/io.bootique.shiro/bootique-shiro/)\n\n# bootique-shiro\n\n## Overview\n\nThis is a set of modules that help to integrate [Apache Shiro](http://shiro.apache.org/) security engine in Bootique apps. \nQuick description of the provided modules:\n\n* `bootique-shiro` - creates a standalone Shiro stack with user-configured security Realms. Includes factories for \n\"Ini\" realm (that supports in-place definition of user accounts) and ActiveDirectory realm. Provides injectable \n`SecurityManager`.\n\n* `bootique-shiro-web` - a module that stands up the Shiro stack and attaches it to a special servlet Filter. Supports\na powerful Shiro feature - [path matching with filters](https://shiro.apache.org/web.html#urls-).\n\n* `bootique-shiro-jdbc` - Provides configurable JDBC realm. Can be used with any of the above modules.\n\nTo use Shiro modules, include Bootique BOM in your project:\n\n```xml\n\u003cdependencyManagement\u003e\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003eio.bootique.bom\u003c/groupId\u003e\n            \u003cartifactId\u003ebootique-bom\u003c/artifactId\u003e\n            \u003cversion\u003e3.0-RC1\u003c/version\u003e\n            \u003ctype\u003epom\u003c/type\u003e\n            \u003cscope\u003eimport\u003c/scope\u003e\n        \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n\u003c/dependencyManagement\u003e\n```\n\n## Usage Standalone\n\nInclude `bootique-shiro` module:\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003eio.bootique.shiro\u003c/groupId\u003e\n\t\u003cartifactId\u003ebootique-shiro\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\nNow you will need to configure your realms. If you have used Apache Shiro outside Bootique, you may be familiar with \nits `.ini` file-based configuration mechanism. We have ported it to a much more flexible Bootique approach that \nis a combination of true dependency injection (DI) with a unified config mechanism (YAML and friends). So you might \ncreate a `.yml` file similar to this (you may recognize some of the configs below that replaced Shiro's \n`[users]`, and `[roles]` sections; `[main]` is mostly handled by DI) :\n\n```yaml\nshiro:\n  realms:\n    - users:\n        adminuser: \"password, admin, user\"\n        user: \"password, user\"\n      roles:\n        admin: \"admin\"\n```\n\n_Hint: use `-H` flag to run your app to see configuration docs in details._\n\n\nFinally you are ready to use Shiro:\n\n```java\n\n@Inject\nprivate SecurityManager securityManager;\n\npublic void doSomething() {\n    new Subject.Builder(securityManager).buildSubject().execute(() -\u003e {\n        \n        // within 'execute' you can access current Subject using Shiro API\n        Subject subject = SecurityUtils.subject();\n        subject.checkPermission(\"A\");\n        subject.checkPermission(\"B\");\n        ...\n    });\n}\n\n```\n\n## Usage - Web\n\nInclude `bootique-shiro-web` module:\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003eio.bootique.shiro\u003c/groupId\u003e\n\t\u003cartifactId\u003ebootique-shiro-web\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\nConfiguring of a web environment includes configuring realms (as described above) as well as URL filters.\n\n```yaml\nshiro:\n  realms:\n    - users:\n        adminuser: \"password, admin, user\"\n        user: \"password, user\"\n      roles:\n        admin: \"admin\"\n        \nshiroweb:\n  # These URLs are resolved within ShiroFilter that routes \n  # them to the corresponding internal security filters.\n  urls:\n    \"/admin\" : perms[\\\"admin\\\"]\n    \"/pub\"   : anon\n```\nUsing Shiro within a servlet request or a JAX-RS endpoint is even easier than a standalone app, as all the environment \nis already initialized for you:\n\n\n```java\n@GET\npublic Response get() {\n    Subject subject = SecurityUtils.getSubject();\n    subject.checkPermission(\"A\");\n    subject.checkPermission(\"B\");\n    ...\n}\n\n```\n\n## Logging and Integration with MDC\n\nOften you may want to associate application logs with a user who performed the action that generated a given set of logs. \nThis helps in investigation of production issues, security audit, etc. This can be achieved using \n[SLF4J MDC](https://logback.qos.ch/manual/mdc.html) (Mapped Diagnostics Context) functionality. `bootique-shiro` \nprovides semi-automated MDC integration facilities. You'd usually start by configuring your logger format to include MDC \nin the output. We are specifically interested in the \"principal\" key, so the format might contain `%X{principal:-?}` pattern:\n\n```yaml\nlog:\n  appenders:\n    - logFormat: '%t %X{principal:-?} %-5p %c{1}: %m%n%ex'\n```\n\nNow you can initialize and cleanup the MDC as appropriate. `bootique-shiro` provides a class called \n[PrincipalMDC](https://github.com/bootique/bootique-shiro/blob/master/bootique-shiro/src/main/java/io/bootique/shiro/mdc/PrincipalMDC.java) \nthat will do that for you. You just call \"reset\" and \"cleanup\" methods as needed.\n\nNow this was the manual approach. If your app is a servlet app and is using `bootique-shiro-web`, MDC initialization and cleanup can be automated. To do that add `bootique-shiro-web-mdc` module to your dependencies:\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003eio.bootique.shiro\u003c/groupId\u003e\n\t\u003cartifactId\u003ebootique-shiro-web-mdc\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\nIf your app authenticates every request separately and is not using Shiro sessions, this (and appender configuration above) is all you need for user names to appear in the logs. But in case the app logs in each user once, and then keeps the Subject in a session, a bit more configuration is needed. You will need an extra filter called \"mdc\" placed in each of your authenticated Shiro chains:\n\n```yaml\nshiroweb:\n  urls:\n    \"/admin\" : perms[\\\"admin\\\"], mdc\n    \"/pub\"   : anon\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbootique%2Fbootique-shiro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbootique%2Fbootique-shiro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbootique%2Fbootique-shiro/lists"}