more conversions
Project: http://git-wip-us.apache.org/repos/asf/shiro-site/repo Commit: http://git-wip-us.apache.org/repos/asf/shiro-site/commit/f8e2bc8d Tree: http://git-wip-us.apache.org/repos/asf/shiro-site/tree/f8e2bc8d Diff: http://git-wip-us.apache.org/repos/asf/shiro-site/diff/f8e2bc8d Branch: refs/heads/master Commit: f8e2bc8dcdd9cbd055cd8443bb9e3357326b932b Parents: 585f846 Author: Brian Demers <[email protected]> Authored: Sat Oct 22 20:01:47 2016 -0500 Committer: Brian Demers <[email protected]> Committed: Sat Oct 22 20:03:11 2016 -0500 ---------------------------------------------------------------------- how-to-contribute.html | 136 ---------------------------------- how-to-contribute.md | 176 ++++++++++++++++++++++++++++++++++++++++++++ inclusionslibrary.html | 22 ------ inclusionslibrary.md | 20 +++++ introduction.html | 46 ------------ introduction.md | 51 +++++++++++++ overview.html | 106 -------------------------- overview.md | 110 +++++++++++++++++++++++++++ 8 files changed, 357 insertions(+), 310 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/how-to-contribute.html ---------------------------------------------------------------------- diff --git a/how-to-contribute.html b/how-to-contribute.html deleted file mode 100644 index b8cc271..0000000 --- a/how-to-contribute.html +++ /dev/null @@ -1,136 +0,0 @@ -<h1><a name="HowtoContribute-ContributingtoApacheShiro"></a>Contributing to Apache Shiro</h1> - -<ul><li><a href="#HowtoContribute-introduction">Introduction</a></li><li><a href="#HowtoContribute-help">Help Wanted Here</a></li><li><a href="#HowtoContribute-procedure">Procedure for reporting bugs and issues and enhancement suggestions</a></li><li><a href="#HowtoContribute-git">Git Usage</a></li><li><a href="#HowtoContribute-committer">Git Committers</a></li><li><a href="#HowtoContribute-issues">Procedure for Raising Development Issues</a></li><li><a href="#HowtoContribute-patches">How to prepare and contribute patches</a></li><li><a href="#HowtoContribute-revert">How to revert changes in Git</a></li><li><a href="#HowtoContribute-tips">Contribution Notes and Tips</a></li></ul> - - -<p><a name="HowtoContribute-introductions"></a></p> -<h2><a name="HowtoContribute-Introduction"></a>Introduction</h2> - -<p>The Shiro Project is an <a class="external-link" href="https://opensource.org/"; rel="nofollow">Open Source</a> volunteer project released under a <a href="license.html" title="License">very liberal license</a>. This means there are many ways to contribute to the project - either with direct participation (coding, documenting, answering questions, proposing ideas, reporting bugs, suggesting bug-fixes, etc..) or by resource donations (staff time, conference presentations, publicity, software) and even general hardware/money <a class="external-link" href="http://www.apache.org/foundation/thanks.html";>donations</a> via the <a class="external-link" href="http://www.apache.org";>Apache Software Foundation</a>.</p> - -<p>To begin with, we suggest you to subscribe to the <a href="mailing-lists.html" title="Mailing Lists">Shiro mailing lists</a> (follow the link for information on how to subscribe and to access the mail list archives). Listen-in for a while, to hear how others make contributions.</p> - -<p>You can get your local working copy of the <a href="download.html" title="Download">latest and greatest code</a> by following the directions in our <a href="download.html" title="Download">Download</a> page. Review the To Do list in the <a class="external-link" href="https://issues.apache.org/jira/browse/SHIRO";>issue tracker</a> and then choose a task that interests you. Perhaps you have noticed something that needs patching, or have a new feature to contribute. Make the changes, do the testing, generate a patch, and discuss on the <a href="mailing-lists.html" title="Mailing Lists">dev mailing list</a>. (Do not worry - the process is easy and explained below.)</p> - -<p>Document writers are usually the most wanted people so if you like to help but you're not familiar with the innermost technical details, don't worry: you can still be tremendously helpful!</p> - -<p><a name="HowtoContribute-help"></a></p> -<h2><a name="HowtoContribute-HelpWantedHere"></a>Help Wanted Here </h2> - -<p>You can be a huge help by providing extra assistance in any of the following areas:</p> - -<ul><li>Assisting to improve documentation and the website.</li><li>Testing Shiro (especially its less-frequently-used features) on various configurations and reporting back.</li><li>New samples for the 'shiro-sample' to concisely describe and demonstrate features. Such samples can also enable automated testing.</li><li>Debugging - producing reproducible test cases and/or finding causes of bugs. Most bugs are recorded as issues (see <a href="#HowtoContribute-procedure">explanation below</a>).</li><li>Providing new use-cases and requirements. If you think that Shiro does not quite meet your needs then tell us about it on the mailing list.</li><li>Specifying/analysing/designing new features - and beyond. If you wish to get further involved with this, please join the <a href="mailing-lists.html" title="Mailing Lists"><tt>shiro-dev</tt> mailing list</a>, install and try out Shiro and read some of the <a href="mailing-lists.html" title="Mailing Lists">mail archives</a>. You should have a reasonable fluency in security technologies, some Java and Maven skills, and a basic understanding of the Shiro architecture - don't just say "it should have XYZ" without reading anything first - because chances are, somebody has already thought of that feature!)</li><li>Packaging easy-to-install packages (such as RPMs) for the myriad of possible configurations out there. (The project does not maintain anything but the basic .zip and .tar.gz packages, but anyone is welcome to build their own specific packages and announce them on the forrest-dev list)</li><li>... and there is just one other thing - don't forget to tell everyone who asks, how great Shiro is! The more people that know about and start to use Shiro, the larger the pool of potential contributors will be.</li></ul> - - -<p><a name="HowtoContribute-procedure"></a></p> -<h2><a name="HowtoContribute-Procedureforreportingbugsandissuesandenhancementsuggestions"></a>Procedure for reporting bugs and issues and enhancement suggestions</h2> - -<p>If you think that you have found a bug or you have a suggestion for improvement, then please discuss it on one of the <a href="mailing-lists.html" title="Mailing Lists">mailing lists</a>. However, please check our <a class="external-link" href="https://issues.apache.org/jira/browse/SHIRO";>issue tracker</a> first as it may be already reported.</p> - -<p>The <a class="external-link" href="https://issues.apache.org/jira/browse/SHIRO";>Apache Shiro Issue Tracker</a> collates our known issues. Obviously not every issue is listed there. Some issues have been discussed on the mailing list but do not yet have an issue recorded.</p> - -<p>The Roadmap is the best way to get an overview. The Unscheduled list also needs regular review, and committers will schedule some of those for the next release.</p> - -<p>When creating a new issue, please provide a concise Summary Title and a short Description. Add further information as Comments and include links to the mail archives. The normal procedure is to discuss the issue on the mailing list and then add relevant notes to the issue tracker, otherwise it becomes cluttered.</p> - -<p><a name="HowtoContribute-git"></a></p> -<h2><a name="HowtoContribute-GitUsage"></a>Git Usage</h2> - -<p>An overview of how to use Git to participate in Shiro development. Do not be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The <a href="download.html" title="Download">Download Shiro</a> page explains how to check-out the code base and build your local copy.</p> - -<p><a name="HowtoContribute-committer"></a></p> -<h2><a name="HowtoContribute-GitCommitters"></a>Git Committers</h2> - -<p>After a developer has consistently provided contributions (code, documentation and discussion) and demonstrated committment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the <a class="external-link" href="http://www.apache.org/dev/";>ASF developers resources</a> especially the <a class="external-link" href="http://www.apache.org/dev/version-control.html";>Source code repositories</a>.</p> - -<p><a name="HowtoContribute-issues"></a></p> -<h2><a name="HowtoContribute-ProcedureforRaisingDevelopmentIssues"></a>Procedure for Raising Development Issues</h2> - -<p>There are two methods for discussing development and submitting patches. So that everyone can be productive, it is important to know which method is appropriate for a certain situation and how to go about it without confusion. This section explains when to use the developer <a href="mailing-lists.html" title="Mailing Lists">mailing list</a> and the <a class="external-link" href="https://issues.apache.org/jira/browse/SHIRO";>issue tracker</a>.</p> - -<p>Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Prepare your post clearly and concisely.</p> - -<p>Most issues will be discovered, resolved, and then patched quickly via the developer mailing list. Larger issues, and ones that are not yet fully understood or are hard to solve, are destined for the issue tracker.</p> - -<p>Experienced developers use the issue tracker directly, as they are very sure when they have found a bug and when not. However, less experienced users should first discuss it on the user or developer mailing list (as appropriate). Impatient people always enter everything into the issue tracker without caring if it is a bug of Shiro or their own installation/configuration mistake - please do not do this.</p> - -<p>As a rule-of-thumb, discuss an issue on the developers mailing list first to work out any details. After it is confirmed to be worthwhile, and you are clear about it, then submit the bug description or patch via Bug Tracking.</p> - -<p>Perhaps you do not get any answer on your first reply, so just post it again until you get one. (But please not every hour - allow a few days for the list to deal with it.) Bear in mind that other countries will have holidays at different times to your country and that they are in different time zones. You might also consider rewriting your initial posting. It may have not been clear to the readers on the mailing list.</p> - -<p><a name="HowtoContribute-patches"></a></p> -<h2><a name="HowtoContribute-Howtoprepareandcontributepatches"></a>Contributing as a Non-Committer</h2> - -<p>If you're a committer on an Apache project, it means that you can commit directly to the project's repository. For instance, with Apache Shiro committers are allowed to directly push commits into the git repository.</p> - -<p>Non-committers, however, have to submit patches for review. Apache Shiro accepts GitHub pull requests. If you are new to Git and GitHub, check these two links:</p> - -<ul> - <li><a class="external-link" href="https://try.github.io/levels/1/challenges/1";>GitHub 15 minutes tutorial</a></li> - <li><a class="external-link" href="https://help.github.com/articles/creating-a-pull-request/";>Creating Pull Requests</a></li> -</ul> - -<p>Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. Submitting GitHub pull requests is the easiest way to get your contribution upstream. For detailed instructions see the link below:</p> -<a href="https://github.com/apache/shiro/blob/master/CONTRIBUTING.md";>GitHub Contribution Guidelines</a> - -<h3><a name="HowtoContribute-submitThroughJIRA">Submitting a patch through JIRA</a></h3> - -<p>While we encourage you to submit your contribution through GitHub pull requests, you can also attach a patch in a JIRA ticket. For the purpose of these instructions, we'll assume that you already have a system with Git and have found a bug to fix or have a feature that you'd like to submit, and you're willing to contribute that code or documentation under the Apache License 2.0.</p> - -<p>Further, if you're fixing a bug we'll assume that you've either filed a bug report (where you will attach your patch) or are submitting a fix for a known bug. If you find a bug and would like to fix it, that's awesome! Please be sure to file the bug too, though.</p> - -<p>If you want to add a feature, you should bring it up for discussion on the [email protected] mailing list before implementing it. This ensures that it meshes with the plans that other contributors have for Apache Shiro, and that you're not doing redundant work. Other developers may also have ideas for the feature or suggestions that will help you land the feature without having to re-do the work. More information about our mailing lists can be found here.</p> - -<p>In short, communication is a vital part of making a contribution to an Apache project.</p> - -<h3><a name="HowtoContribute-gettingStartedGit">Getting Started</a></h3> - -<p>First, lets make sure that you've added your name and email to your `~/.gitconfig`:</p> - -<pre> -$ git config --global user.name "Your Name" -$ git config --global user.email [email protected] -</pre> -You'll grab the Shiro source with git: - -<pre> -$ git clone https://git-wip-us.apache.org/repos/asf/shiro.git -</pre> - -<p>If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache Shiro development can move pretty fast!)</p> - -<pre> -$ git checkout -b mybranch -</pre> - -<p>This does two things: One, it creates the branch mybranch and two, it changes your working branch to mybranch. Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch, like so:</p> - -<pre> -[user@localhost shiro]$ git branch -master -* mybranch -</pre> - -<p>Make whatever changes you're going to make, be sure to use git add to stage the changes, and then you're going to commit the changes to your working branch:</p> - -<pre> -git commit -m "Insert a meaningful summary of changes here." -</pre> - -<p>Finally, you can create a patch and attach it to the JIRA issue that you created for the bug you are fixing.</p> - -<pre> -git format-patch master --stdout > ~/patch-name.patch -</pre> - -<h3><a name="HowtoContribute-review">Review</a></h3> - -<p>Once you've submitted your pull request, you should receive a response within a few days. If you receive no response within a week, please ping the shiro-dev mailing list ([email protected]).</p> - -<p><a name="HowtoContribute-tips"></a></p> -<h2><a name="HowtoContribute-ContributionNotesandTips"></a>Contribution Notes and Tips</h2> - -<p>This is a collection of tips for contributing to the project in a manner that is productive for all parties.</p> - -<ul><li>See general ASF <a class="external-link" href="http://www.apache.org/dev/contrib-email-tips.html";>Tips for email contributors</a></li><li>There is no such thing as a dumb question. Always check the <a href="mailing-lists.html" title="Mailing Lists">archives</a> to see if someone else asked it first and maybe already received an answer.</li><li>Every contribution is worthwhile. Even if the code isn't perfect. Even if the documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve and get ever closer to "perfect".</li><li>Use sensible and concise email subject headings. Search engines, and humans trying to browse a voluminous list, will respond favourably to a descriptive title.</li><li>Start new threads with new Subject for new topics, rather than reusing the previous Subject line.</li><li>Keep each topic focused. If som e new topic arises then start a new discussion. This leaves the original topic to continue uncluttered.<br clear="none"> -Whenever you decide to start a new topic, then start with a fresh new email message window. Do not use the "Reply to" button, because threaded mail-readers get confused (they utilise the In-reply-to header). If so, then your new topic will get lost in the previous thread and go unanswered.</li><li>Prepend your email subject line with a marker when that is appropriate, e.g. [Proposal], [RT] (Random Thought which quickly blossom into research topics <img align="middle" class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/smile.png"; height="20" width="20" alt="" border="0">, [STATUS] (development status of a certain facility).</li><li>Remember that most people are participating in development on a volunteer basis and in their "spare time". These enthusiasts will attempt to respond to issues. It may take a little while to get your answers.</li><li>Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Do not just perceive a problem and then rush out with a question - instead, delve.</li><li>Try to at least offer a partial solution and not just a problem statement.</li><li>Take the time to clearly explain your issue and write a concise email message. Less confusion facilitates fast and complete resolution.</li><li>Do not bother to send an email reply that simply says "thanks". When the issue is resolved, that is the finish - end of thread. Reduce clutter.</li><li>You would usually do any development work against the master branch in Git.</li><li>When sending a patch, you usually do not need to worry about which Git branch it should be applied to. The maintainers of the repository will decide.</li><li>Keep all project-related discussion on the mailing list. It is much better to utilise the wider audience, rather than to break off into private discussion groups. You never know who else will have the answer to your issues, and anyway other people are interested in the outcome.</li><li>Become familiar with the mailing lists. As you browse and search, you will see the way other people do things. Follow the leading examples.</li></ul> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/how-to-contribute.md ---------------------------------------------------------------------- diff --git a/how-to-contribute.md b/how-to-contribute.md new file mode 100644 index 0000000..d22e4e3 --- /dev/null +++ b/how-to-contribute.md @@ -0,0 +1,176 @@ +<a name="HowtoContribute-ContributingtoApacheShiro"></a> +#Contributing to Apache Shiro + +* [Introduction](#HowtoContribute-introduction) +* [Help Wanted Here](#HowtoContribute-help) +* [Procedure for reporting bugs and issues and enhancement suggestions](#HowtoContribute-procedure) +* [Git Usage](#HowtoContribute-git) +* [Git Committers](#HowtoContribute-committer) +* [Procedure for Raising Development Issues](#HowtoContribute-issues) +* [How to prepare and contribute patches](#HowtoContribute-patches) +* [How to revert changes in Git](#HowtoContribute-revert) +* [Contribution Notes and Tips](#HowtoContribute-tips) + +<a name="HowtoContribute-introductions"></a> +<a name="HowtoContribute-Introduction"></a> +##Introduction + +The Shiro Project is an [Open Source](https://opensource.org/) volunteer project released under a [very liberal license](license.html "License"). This means there are many ways to contribute to the project - either with direct participation (coding, documenting, answering questions, proposing ideas, reporting bugs, suggesting bug-fixes, etc..) or by resource donations (staff time, conference presentations, publicity, software) and even general hardware/money [donations](http://www.apache.org/foundation/thanks.html) via the [Apache Software Foundation](http://www.apache.org). + +To begin with, we suggest you to subscribe to the [Shiro mailing lists](mailing-lists.html "Mailing Lists") (follow the link for information on how to subscribe and to access the mail list archives). Listen-in for a while, to hear how others make contributions. + +You can get your local working copy of the [latest and greatest code](download.html "Download") by following the directions in our [Download](download.html "Download") page. Review the To Do list in the [issue tracker](https://issues.apache.org/jira/browse/SHIRO) and then choose a task that interests you. Perhaps you have noticed something that needs patching, or have a new feature to contribute. Make the changes, do the testing, generate a patch, and discuss on the [dev mailing list](mailing-lists.html "Mailing Lists"). (Do not worry - the process is easy and explained below.) + +Document writers are usually the most wanted people so if you like to help but you're not familiar with the innermost technical details, don't worry: you can still be tremendously helpful! + +<a name="HowtoContribute-help"></a> +<a name="HowtoContribute-HelpWantedHere"></a> +##Help Wanted Here + +You can be a huge help by providing extra assistance in any of the following areas: + +* Assisting to improve documentation and the website. +* Testing Shiro (especially its less-frequently-used features) on various configurations and reporting back. +* New samples for the 'shiro-sample' to concisely describe and demonstrate features. Such samples can also enable automated testing. +* Debugging - producing reproducible test cases and/or finding causes of bugs. Most bugs are recorded as issues (see [explanation below](#HowtoContribute-procedure)). +* Providing new use-cases and requirements. If you think that Shiro does not quite meet your needs then tell us about it on the mailing list. +* Specifying/analysing/designing new features - and beyond. If you wish to get further involved with this, please join the [`shiro-dev` mailing list](mailing-lists.html "Mailing Lists"), install and try out Shiro and read some of the [mail archives](mailing-lists.html "Mailing Lists"). You should have a reasonable fluency in security technologies, some Java and Maven skills, and a basic understanding of the Shiro architecture - don't just say "it should have XYZ" without reading anything first - because chances are, somebody has already thought of that feature!) +* Packaging easy-to-install packages (such as RPMs) for the myriad of possible configurations out there. (The project does not maintain anything but the basic .zip and .tar.gz packages, but anyone is welcome to build their own specific packages and announce them on the forrest-dev list) +* ... and there is just one other thing - don't forget to tell everyone who asks, how great Shiro is! The more people that know about and start to use Shiro, the larger the pool of potential contributors will be. + +<a name="HowtoContribute-procedure"></a> +<a name="HowtoContribute-Procedureforreportingbugsandissuesandenhancementsuggestions"></a> +##Procedure for reporting bugs and issues and enhancement suggestions + +If you think that you have found a bug or you have a suggestion for improvement, then please discuss it on one of the [mailing lists](mailing-lists.html "Mailing Lists"). However, please check our [issue tracker](https://issues.apache.org/jira/browse/SHIRO) first as it may be already reported. + +The [Apache Shiro Issue Tracker](https://issues.apache.org/jira/browse/SHIRO) collates our known issues. Obviously not every issue is listed there. Some issues have been discussed on the mailing list but do not yet have an issue recorded. + +The Roadmap is the best way to get an overview. The Unscheduled list also needs regular review, and committers will schedule some of those for the next release. + +When creating a new issue, please provide a concise Summary Title and a short Description. Add further information as Comments and include links to the mail archives. The normal procedure is to discuss the issue on the mailing list and then add relevant notes to the issue tracker, otherwise it becomes cluttered. + +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage + +An overview of how to use Git to participate in Shiro development. Do not be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. + +<a name="HowtoContribute-committer"></a> +<a name="HowtoContribute-GitCommitters"></a> +## Git Committers + +After a developer has consistently provided contributions (code, documentation and discussion) and demonstrated committment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the [ASF developers resources](http://www.apache.org/dev/) especially the [Source code repositories](http://www.apache.org/dev/version-control.html). + +<a name="HowtoContribute-issues"></a> +<a name="HowtoContribute-ProcedureforRaisingDevelopmentIssues"></a> +## Procedure for Raising Development Issues + +There are two methods for discussing development and submitting patches. So that everyone can be productive, it is important to know which method is appropriate for a certain situation and how to go about it without confusion. This section explains when to use the developer [mailing list](mailing-lists.html "Mailing Lists") and the [issue tracker](https://issues.apache.org/jira/browse/SHIRO). + +Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Prepare your post clearly and concisely. + +Most issues will be discovered, resolved, and then patched quickly via the developer mailing list. Larger issues, and ones that are not yet fully understood or are hard to solve, are destined for the issue tracker. + +Experienced developers use the issue tracker directly, as they are very sure when they have found a bug and when not. However, less experienced users should first discuss it on the user or developer mailing list (as appropriate). Impatient people always enter everything into the issue tracker without caring if it is a bug of Shiro or their own installation/configuration mistake - please do not do this. + +As a rule-of-thumb, discuss an issue on the developers mailing list first to work out any details. After it is confirmed to be worthwhile, and you are clear about it, then submit the bug description or patch via Bug Tracking. + +Perhaps you do not get any answer on your first reply, so just post it again until you get one. (But please not every hour - allow a few days for the list to deal with it.) Bear in mind that other countries will have holidays at different times to your country and that they are in different time zones. You might also consider rewriting your initial posting. It may have not been clear to the readers on the mailing list. + +<a name="HowtoContribute-patches"></a> +<a name="HowtoContribute-Howtoprepareandcontributepatches"></a> +##Contributing as a Non-Committer + +If you're a committer on an Apache project, it means that you can commit directly to the project's repository. For instance, with Apache Shiro committers are allowed to directly push commits into the git repository. + +Non-committers, however, have to submit patches for review. Apache Shiro accepts GitHub pull requests. If you are new to Git and GitHub, check these two links: + +* [GitHub 15 minutes tutorial](https://try.github.io/levels/1/challenges/1) +* [Creating Pull Requests](https://help.github.com/articles/creating-a-pull-request/) + +Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. Submitting GitHub pull requests is the easiest way to get your contribution upstream. For detailed instructions see the link below: + +[GitHub Contribution Guidelines](https://github.com/apache/shiro/blob/master/CONTRIBUTING.md) + +<a name="HowtoContribute-submitThroughJIRA"></a> +###Submitting a patch through JIRA + +While we encourage you to submit your contribution through GitHub pull requests, you can also attach a patch in a JIRA ticket. For the purpose of these instructions, we'll assume that you already have a system with Git and have found a bug to fix or have a feature that you'd like to submit, and you're willing to contribute that code or documentation under the Apache License 2.0. + +Further, if you're fixing a bug we'll assume that you've either filed a bug report (where you will attach your patch) or are submitting a fix for a known bug. If you find a bug and would like to fix it, that's awesome! Please be sure to file the bug too, though. + +If you want to add a feature, you should bring it up for discussion on the [email protected] mailing list before implementing it. This ensures that it meshes with the plans that other contributors have for Apache Shiro, and that you're not doing redundant work. Other developers may also have ideas for the feature or suggestions that will help you land the feature without having to re-do the work. More information about our mailing lists can be found here. + +In short, communication is a vital part of making a contribution to an Apache project. + +<a name="HowtoContribute-gettingStartedGit"></a> +###Getting Started + +First, lets make sure that you've added your name and email to your `~/.gitconfig`: + +``` bash +$ git config --global user.name "Your Name" +$ git config --global user.email [email protected] +``` + +You'll grab the Shiro source with git: + +``` bash +$ git clone https://git-wip-us.apache.org/repos/asf/shiro.git +``` + +If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache Shiro development can move pretty fast!) + +``` bash +$ git checkout -b mybranch +``` + +This does two things: One, it creates the branch mybranch and two, it changes your working branch to mybranch. Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch, like so: + +``` bash +[user@localhost shiro]$ git branch +master +* mybranch +``` + +Make whatever changes you're going to make, be sure to use git add to stage the changes, and then you're going to commit the changes to your working branch: + +``` bash +git commit -m "Insert a meaningful summary of changes here." +``` + +Finally, you can create a patch and attach it to the JIRA issue that you created for the bug you are fixing. + +``` bash +git format-patch master --stdout > ~/patch-name.patch +``` + +<a name="HowtoContribute-review"></a> +###Review + +Once you've submitted your pull request, you should receive a response within a few days. If you receive no response within a week, please ping the shiro-dev mailing list ([email protected]). + +<a name="HowtoContribute-tips"></a> +<a name="HowtoContribute-ContributionNotesandTips"></a> +##Contribution Notes and Tips + +This is a collection of tips for contributing to the project in a manner that is productive for all parties. + +* See general ASF [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html) +* There is no such thing as a dumb question. Always check the [archives](mailing-lists.html "Mailing Lists") to see if someone else asked it first and maybe already received an answer. +* Every contribution is worthwhile. Even if the code isn't perfect. Even if the documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve and get ever closer to "perfect". +* Use sensible and concise email subject headings. Search engines, and humans trying to browse a voluminous list, will respond favourably to a descriptive title. +* Start new threads with new Subject for new topics, rather than reusing the previous Subject line. +* Keep each topic focused. If some new topic arises then start a new discussion. This leaves the original topic to continue uncluttered. + Whenever you decide to start a new topic, then start with a fresh new email message window. Do not use the "Reply to" button, because threaded mail-readers get confused (they utilise the In-reply-to header). If so, then your new topic will get lost in the previous thread and go unanswered. +* Prepend your email subject line with a marker when that is appropriate, e.g. [Proposal], [RT] (Random Thought which quickly blossom into research topics , [STATUS] (development status of a certain facility). +* Remember that most people are participating in development on a volunteer basis and in their "spare time". These enthusiasts will attempt to respond to issues. It may take a little while to get your answers. +* Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Do not just perceive a problem and then rush out with a question - instead, delve. +* Try to at least offer a partial solution and not just a problem statement. +* Take the time to clearly explain your issue and write a concise email message. Less confusion facilitates fast and complete resolution. +* Do not bother to send an email reply that simply says "thanks". When the issue is resolved, that is the finish - end of thread. Reduce clutter. +* You would usually do any development work against the master branch in Git. +* When sending a patch, you usually do not need to worry about which Git branch it should be applied to. The maintainers of the repository will decide. +* Keep all project-related discussion on the mailing list. It is much better to utilise the wider audience, rather than to break off into private discussion groups. You never know who else will have the answer to your issues, and anyway other people are interested in the outcome. +* Become familiar with the mailing lists. As you browse and search, you will see the way other people do things. Follow the leading examples. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/inclusionslibrary.html ---------------------------------------------------------------------- diff --git a/inclusionslibrary.html b/inclusionslibrary.html deleted file mode 100644 index e199155..0000000 --- a/inclusionslibrary.html +++ /dev/null @@ -1,22 +0,0 @@ -<p>The children of this page contain information which is <b>included in other pages</b>. This is a library of re-usable information chunks. </p> - -<p>If you want to change any of these pages, be aware that: </p> -<ul><li>Changing page names is problematic — you will need to change all the {include} and {excerpt-include} macros manually.</li><li>The content is used in many places — make sure your change is generic enough to fit the contexts in which the pages are used.</li></ul> - - -<p>To include an excerpt from a page: </p> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -{excerpt-include:_page name|nopanel=<span class="code-keyword">true</span>} -</pre> -</div></div> -<p>Note that the page titled '_page name' must contain the {excerpt} macro, otherwise the {excerpt-include} will not work. </p> - -<p>To include the entire contents of a page" </p> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -{include:page name|nopanel=<span class="code-keyword">true</span>} -</pre> -</div></div> - -<h6><a name="_InclusionsLibrary-ChildrenofthisPage"></a>Children of this Page </h6> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/inclusionslibrary.md ---------------------------------------------------------------------- diff --git a/inclusionslibrary.md b/inclusionslibrary.md new file mode 100644 index 0000000..c4b0506 --- /dev/null +++ b/inclusionslibrary.md @@ -0,0 +1,20 @@ +The children of this page contain information which is **included in other pages**. This is a library of re-usable information chunks. + +If you want to change any of these pages, be aware that: + +* Changing page names is problematic â you will need to change all the {include} and {excerpt-include} macros manually. +* The content is used in many places â make sure your change is generic enough to fit the contexts in which the pages are used. + +To include an excerpt from a page: + +``` +{excerpt-include:_page name|nopanel=true} +``` + +Note that the page titled '_page name' must contain the {excerpt} macro, otherwise the {excerpt-include} will not work. + +To include the entire contents of a page" + +``` +{include:page name|nopanel=true} +``` http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/introduction.html ---------------------------------------------------------------------- diff --git a/introduction.html b/introduction.html deleted file mode 100644 index 6f7b746..0000000 --- a/introduction.html +++ /dev/null @@ -1,46 +0,0 @@ -<h1><a name="Introduction-IntroductiontoApacheShiro"></a>Introduction to Apache Shiro</h1> - -<h2><a name="Introduction-WhatisApacheShiro%3F"></a>What is Apache Shiro?</h2> - -<p>Apache Shiro is a powerful and flexible open-source security framework that cleanly handles authentication, authorization, enterprise session management and cryptography.</p> - -<p>Apache Shiro's first and foremost goal is to be easy to use and understand. Security can be very complex at times, even painful, but it doesn't have to be. A framework should mask complexities where possible and expose a clean and intuitive API that simplifies the developer's effort to make their application(s) secure.</p> - -<p>Here are some things that you can do with Apache Shiro:</p> - -<ul><li>Authenticate a user to verify their identity</li><li>Perform access control for a user, such as: - <ul><li>Determine if a user is assigned a certain security role or not</li><li>Determine if a user is permitted to do something or not</li></ul> - </li><li>Use a Session API in any environment, even without web or EJB containers.</li><li>React to events during authentication, access control, or during a session's lifetime.</li><li>Aggregate 1 or more data sources of user security data and present this all as a single composite user 'view'.</li><li>Enable Single Sign On (SSO) functionality</li><li>Enable 'Remember Me' services for user association without login<br clear="none"> -...<br clear="none"> -and much more - all integrated into a cohesive easy-to-use API.</li></ul> - - -<p>Shiro attempts to achieve these goals for all application environments - from the simplest command line application to the largest enterprise applications, without forcing dependencies on other 3rd party frameworks, containers, or application servers. Of course the project aims to integrate into these environments wherever possible, but it could be used out-of-the-box in any environment.</p> - -<h2><a name="Introduction-ApacheShiroFeatures"></a>Apache Shiro Features</h2> - -<p>Apache Shiro is a comprehensive application security framework with many features. The following diagram shows where Shiro focuses its energy, and this reference manual will be organized similarly:</p> - -<p><br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<span class="image-wrap" style="display: block; text-align: center"><img src="assets/images/ShiroFeatures.png" style="border: 0px solid black"></span> -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></p> - -<p>Shiro targets what the Shiro development team calls "the four cornerstones of application security" - Authentication, Authorization, Session Management, and Cryptography:</p> - -<ul><li><b>Authentication:</b> Sometimes referred to as 'login', this is the act of proving a user is who they say they are. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Authorization:</b> The process of access control, i.e. determining 'who' has access to 'what'. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Session Management:</b> Managing user-specific sessions, even in non-web or EJB applications. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Cryptography:</b> Keeping data secure using cryptographic algorithms while still being easy to use.</li></ul> - - -<p>There are also additional features to support and reinforce these concerns in different application environments, especially:</p> - -<ul><li>Web Support: Shiro's web support APIs help easily secure web applications.</li><li>Caching: Caching is a first-tier citizen in Apache Shiro's API to ensure that security operations remain fast and efficient.</li><li>Concurrency: Apache Shiro supports multi-threaded applications with its concurrency features.</li><li>Testing: Test support exists to help you write unit and integration tests and ensure your code will be secured as expected.</li><li>"Run As": A feature that allows users to assume the identity of another user (if they are allowed), sometimes useful in administrative scenarios.</li><li>"Remember Me": Remember users' identities across sessions so they only need to log in when mandatory.</li></ul> - - -<p></p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/introduction.md ---------------------------------------------------------------------- diff --git a/introduction.md b/introduction.md new file mode 100644 index 0000000..c9b6fa4 --- /dev/null +++ b/introduction.md @@ -0,0 +1,51 @@ +<a name="Introduction-IntroductiontoApacheShiro"></a> +#Introduction to Apache Shiro + +<a name="Introduction-WhatisApacheShiro%3F"></a> +##What is Apache Shiro? + +Apache Shiro is a powerful and flexible open-source security framework that cleanly handles authentication, authorization, enterprise session management and cryptography. + +Apache Shiro's first and foremost goal is to be easy to use and understand. Security can be very complex at times, even painful, but it doesn't have to be. A framework should mask complexities where possible and expose a clean and intuitive API that simplifies the developer's effort to make their application(s) secure. + +Here are some things that you can do with Apache Shiro: + +* Authenticate a user to verify their identity +* Perform access control for a user, such as: + * Determine if a user is assigned a certain security role or not + * Determine if a user is permitted to do something or not +* Use a Session API in any environment, even without web or EJB containers. +* React to events during authentication, access control, or during a session's lifetime. +* Aggregate 1 or more data sources of user security data and present this all as a single composite user 'view'. +* Enable Single Sign On (SSO) functionality +* Enable 'Remember Me' services for user association without login +... +and much more - all integrated into a cohesive easy-to-use API. + +Shiro attempts to achieve these goals for all application environments - from the simplest command line application to the largest enterprise applications, without forcing dependencies on other 3rd party frameworks, containers, or application servers. Of course the project aims to integrate into these environments wherever possible, but it could be used out-of-the-box in any environment. + +<a name="Introduction-ApacheShiroFeatures"></a> +##Apache Shiro Features + +Apache Shiro is a comprehensive application security framework with many features. The following diagram shows where Shiro focuses its energy, and this reference manual will be organized similarly: + +<img src="assets/images/ShiroFeatures.png" style="margin:0px auto;display:block"></img> + +Shiro targets what the Shiro development team calls "the four cornerstones of application security" - Authentication, Authorization, Session Management, and Cryptography: + +* **Authentication:** Sometimes referred to as 'login', this is the act of proving a user is who they say they are. + +* **Authorization:** The process of access control, i.e. determining 'who' has access to 'what'. + +* **Session Management:** Managing user-specific sessions, even in non-web or EJB applications. + +* **Cryptography:** Keeping data secure using cryptographic algorithms while still being easy to use. + +There are also additional features to support and reinforce these concerns in different application environments, especially: + +* Web Support: Shiro's web support APIs help easily secure web applications. +* Caching: Caching is a first-tier citizen in Apache Shiro's API to ensure that security operations remain fast and efficient. +* Concurrency: Apache Shiro supports multi-threaded applications with its concurrency features. +* Testing: Test support exists to help you write unit and integration tests and ensure your code will be secured as expected. +* "Run As": A feature that allows users to assume the identity of another user (if they are allowed), sometimes useful in administrative scenarios. +* "Remember Me": Remember users' identities across sessions so they only need to log in when mandatory. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/overview.html ---------------------------------------------------------------------- diff --git a/overview.html b/overview.html deleted file mode 100644 index d802d2f..0000000 --- a/overview.html +++ /dev/null @@ -1,106 +0,0 @@ -<h1><a name="Overview-OverviewofApacheShiro"></a>Overview of Apache Shiro</h1> - -<h2><a name="Overview-Introduction"></a>Introduction</h2> - -<p>Apache Shiro is a powerful and flexible open-source security framework that cleanly handles authentication, authorization, enterprise session management and cryptography.</p> - -<p>Apache Shiro's first and foremost goal is to be easy to use and understand. Security can be very complex at times, even painful, but it doesn't have to be. A framework should mask complexities where possible and expose a clean and intuitive API that simplifies the developer's effort to make their application(s) secure.</p> - -<p>Here are some things that you can do with Apache Shiro:</p> - -<ul><li>Authenticate a user to verify their identity</li><li>Perform access control for a user, such as: - <ul><li>Determine if a user is assigned a certain security role or not</li><li>Determine if a user is permitted to do something or not</li></ul> - </li><li>Use a Session API in any environment, even without web or EJB containers.</li><li>React to events during authentication, access control, or during a session's lifetime.</li><li>Aggregate 1 or more data sources of user security data and present this all as a single composite user 'view'.</li><li>Enable Single Sign On (SSO) functionality</li><li>Enable 'Remember Me' services for user association without login<br clear="none"> -...<br clear="none"> -and much more - all integrated into a cohesive easy-to-use API.</li></ul> - - -<p>Shiro attempts to achieve these goals for all application environments - from the simplest command line application to the largest enterprise applications, without forcing dependencies on other 3rd party frameworks, containers, or application servers. Of course the project aims to integrate into these environments wherever possible, but it could be used out-of-the-box in any environment.</p> - -<h2><a name="Overview-Features"></a>Features</h2> - -<p>Apache Shiro is a comprehensive application security framework with many features. The following diagram shows where Shiro focuses its energy, and this reference manual will be organized similarly:</p> - -<p><br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<span class="image-wrap" style="display: block; text-align: center"><img src="overview.data/ShiroFeatures.png" style="border: 0px solid black"></span> -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></p> - -<p>Shiro targets what the Shiro development team calls "the four cornerstones of application security" - Authentication, Authorization, Session Management, and Cryptography:</p> - -<ul><li><b>Authentication:</b> Sometimes referred to as 'login', this is the act of proving a user is who they say they are. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Authorization:</b> The process of access control, i.e. determining 'who' has access to 'what'. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Session Management:</b> Managing user-specific sessions, even in non-web or EJB applications. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Cryptography:</b> Keeping data secure using cryptographic algorithms while still being easy to use.</li></ul> - - -<p>There are also additional features to support and reinforce these concerns in different application environments, especially:</p> - -<ul><li>Web Support: Shiro's web support APIs help easily secure web applications.</li><li>Caching: Caching is a first-tier citizen in Apache Shiro's API to ensure that security operations remain fast and efficient.</li><li>Concurrency: Apache Shiro supports multi-threaded applications with its concurrency features.</li><li>Testing: Test support exists to help you write unit and integration tests and ensure your code will be secured as expected.</li><li>"Run As": A feature that allows users to assume the identity of another user (if they are allowed), sometimes useful in administrative scenarios.</li><li>"Remember Me": Remember users' identities across sessions so they only need to log in when mandatory.</li></ul> - - -<p></p> - -<h2><a name="Overview-AFirstLookatApacheShiro"></a>A First Look at Apache Shiro</h2> - -<p>Apache Shiro's design goals are to simplify application security by being intuitive and easy to use. Shiro's core design models how most people think about application security - in the context of someone (or something) interacting with an application.</p> - -<p>Software applications are usually designed based on user stories. That is, you'll often design user interfaces or service APIs based on how a user would (or should) interact with the software. For example, you might say, "If the user interacting with my application is logged in, I will show them a button they can click to view their account information. If they are not logged in, I will show a sign-up button." </p> - -<p>This example statement indicates that applications are largely written to satisfy user requirements and needs. Even if the 'user' is another software system and not a human being, you still write code to reflect behavior based on who (or what) is currently interacting with your software.</p> - -<p>Shiro largely reflects these concepts in its own design. By matching what is already intuitive for software developers, Apache Shiro remains intuitive and easy to use in practically any application.</p> - -<h3><a name="Overview-BasicDesign"></a>Basic Design</h3> - -<p>Shiro's architecture has 3 primary concepts: the <tt>Subject</tt>, <tt>SecurityManager</tt> and <tt>Realm</tt> s. The following diagram is a high-level overview of how these concepts interact, and we'll cover each concept below:</p> - -<p><br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<span class="image-wrap" style="display: block; text-align: center"><img src="overview.data/ShiroBasicArchitecture.png" style="border: 0px solid black"></span> -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></p> - -<h4><a name="Overview-Subject"></a>Subject</h4> - -<p>The <tt>Subject</tt> is essentially a security specific 'view' of the the currently executing user. Notice that it is not actually named <em>User</em> however. The name <em>Subject</em> was chosen for two reasons: </p> - -<ol><li>The word 'User' often implies a human being in many software systems. But sometimes the 'currently executing user' isn't a human being at all - maybe it is a 3rd-party process or remote server or daemon account. The word 'Subject' is more general and can mean 'the entity interacting with the software'.</li><li>The word 'Subject', because it is a general-purpose concept, is the actual term most often used in the security world. We retain that definition to be consistent.</li></ol> - - -<p>You can acquire the current <tt>Subject</tt> anywhere in your application code as shown here:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.subject.Subject; -<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils; -... -Subject currentUser = SecurityUtils.getSubject(); -</pre> -</div></div> - -<p>Once you have a <tt>Subject</tt> instance, you immediately have access to 90% of everything you would ever need to do to perform security for that Subject, such as login and logout, perform role and permission checks, access their session, and more - but more about this later. The most important thing to know is that the <tt>Subject</tt> is your 'security-specific view' of an application 'user' and that you can essentially access this anywhere in application code to perform whatever security operations you need. </p> - -<h4><a name="Overview-TheSecurityManager"></a>The SecurityManager</h4> - -<p>While application developers almost exclusively interact with <tt>Subject</tt> instances in their code, Subjects have a 'behind the scenes' counterpart that makes them work - the Shiro <tt>SecurityManager</tt> (note this is <em>not</em> the same thing as the <tt>java.lang.SecurityManager</tt>).</p> - -<p>While a <tt>Subject</tt> instance represents security information and operations for a single user, the Shiro <tt>SecurityManager</tt> manages security operations for <em>all</em> users. It is essentially the 'man behind the curtain' that manages all features in Shiro for all Subjects. Each software application that uses Shiro typically has one and only one <tt>SecurityManager</tt> instance.</p> - -<p>The <tt>SecurityManager</tt> is the heart of Shiro’s architecture and acts as a sort of 'umbrella’ object that coordinates internally nested security components that form an object graph. However, once the SecurityManager and its internal object graph is configured, it is usually left alone and application developers spend almost all of their time with the <tt>Subject</tt> API.</p> - -<p>We will talk about the <tt>SecurityManager</tt> in detail later on, but it is important to realize that when you interact with a <tt>Subject</tt>, it is really the <tt>SecurityManager</tt> behind the scenes that does all the heavy lifting for any <tt>Subject</tt> security operation. This is reflected in the basic flow diagram above.</p> - -<h4><a name="Overview-Realms"></a>Realms</h4> - -<p>The third and final core concept in Shiro is that of a Realm. A Realm acts as the ‘bridge’ or ‘connector’ between Shiro and your application’s security data. That is, when it comes time to actually interact with security-related data like user accounts to perform authentication (login) and authorization (access control), Shiro looks up many of these things from one or more Realms configured for an application.</p> - -<p>In this sense a Realm is essentially a security-specific <a class="external-link" href="https://en.wikipedia.org/wiki/Data_access_object"; rel="nofollow">DAO</a>: it encapsulates connection details for data sources and makes the associated data available to Shiro as needed. When configuring Shiro, you must specify at least one Realm to use for authentication and/or authorization. More than one Realm may be configured, but at least one is required.</p> - -<p>Shiro provides out-of-the-box Realms to connect to a number of security data sources (aka directories) such as LDAP, relational databases (JDBC), text configuration sources like INI and properties files, and more. You can plug-in your own Realm implementations to represent custom data sources if the default Realms do not meet your needs.</p> - -<p>Like other internal components, the Shiro <tt>SecurityManager</tt> manages how Realms are used to acquire security data and then represented as <tt>Subject</tt> instances.</p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f8e2bc8d/overview.md ---------------------------------------------------------------------- diff --git a/overview.md b/overview.md new file mode 100644 index 0000000..94c3471 --- /dev/null +++ b/overview.md @@ -0,0 +1,110 @@ +<a name="Overview-OverviewofApacheShiro"></a> +#Overview of Apache Shiro + +<a name="Overview-Introduction"></a> +##Introduction + +Apache Shiro is a powerful and flexible open-source security framework that cleanly handles authentication, authorization, enterprise session management and cryptography. + +Apache Shiro's first and foremost goal is to be easy to use and understand. Security can be very complex at times, even painful, but it doesn't have to be. A framework should mask complexities where possible and expose a clean and intuitive API that simplifies the developer's effort to make their application(s) secure. + +Here are some things that you can do with Apache Shiro: + +* Authenticate a user to verify their identity +* Perform access control for a user, such as: + * Determine if a user is assigned a certain security role or not + * Determine if a user is permitted to do something or not +* Use a Session API in any environment, even without web or EJB containers. +* React to events during authentication, access control, or during a session's lifetime. +* Aggregate 1 or more data sources of user security data and present this all as a single composite user 'view'. +* Enable Single Sign On (SSO) functionality +* Enable 'Remember Me' services for user association without login +... +and much more - all integrated into a cohesive easy-to-use API. + +Shiro attempts to achieve these goals for all application environments - from the simplest command line application to the largest enterprise applications, without forcing dependencies on other 3rd party frameworks, containers, or application servers. Of course the project aims to integrate into these environments wherever possible, but it could be used out-of-the-box in any environment. + +<a name="Overview-Features"></a> +##Features + +Apache Shiro is a comprehensive application security framework with many features. The following diagram shows where Shiro focuses its energy, and this reference manual will be organized similarly: + +<img src="assets/images/ShiroFeatures.png" style="margin:0px auto;display:block"></img> + +Shiro targets what the Shiro development team calls "the four cornerstones of application security" - Authentication, Authorization, Session Management, and Cryptography: + +* **Authentication:** Sometimes referred to as 'login', this is the act of proving a user is who they say they are. + +* **Authorization:** The process of access control, i.e. determining 'who' has access to 'what'. + +* **Session Management:** Managing user-specific sessions, even in non-web or EJB applications. + +* **Cryptography:** Keeping data secure using cryptographic algorithms while still being easy to use. + +There are also additional features to support and reinforce these concerns in different application environments, especially: + +* Web Support: Shiro's web support APIs help easily secure web applications. +* Caching: Caching is a first-tier citizen in Apache Shiro's API to ensure that security operations remain fast and efficient. +* Concurrency: Apache Shiro supports multi-threaded applications with its concurrency features. +* Testing: Test support exists to help you write unit and integration tests and ensure your code will be secured as expected. +* "Run As": A feature that allows users to assume the identity of another user (if they are allowed), sometimes useful in administrative scenarios. +* "Remember Me": Remember users' identities across sessions so they only need to log in when mandatory. + +<a name="Overview-AFirstLookatApacheShiro"></a> +##A First Look at Apache Shiro + +Apache Shiro's design goals are to simplify application security by being intuitive and easy to use. Shiro's core design models how most people think about application security - in the context of someone (or something) interacting with an application. + +Software applications are usually designed based on user stories. That is, you'll often design user interfaces or service APIs based on how a user would (or should) interact with the software. For example, you might say, "If the user interacting with my application is logged in, I will show them a button they can click to view their account information. If they are not logged in, I will show a sign-up button." + +This example statement indicates that applications are largely written to satisfy user requirements and needs. Even if the 'user' is another software system and not a human being, you still write code to reflect behavior based on who (or what) is currently interacting with your software. + +Shiro largely reflects these concepts in its own design. By matching what is already intuitive for software developers, Apache Shiro remains intuitive and easy to use in practically any application. + +<a name="Overview-BasicDesign"></a> +###Basic Design + +Shiro's architecture has 3 primary concepts: the `Subject`, `SecurityManager` and `Realm` s. The following diagram is a high-level overview of how these concepts interact, and we'll cover each concept below: + +<img src="assets/images/ShiroBasicArchitecture.png" style="margin:0px auto;display:block"></img> + +<a name="Overview-Subject"></a> +####Subject + +The `Subject` is essentially a security specific 'view' of the the currently executing user. Notice that it is not actually named _User_ however. The name _Subject_ was chosen for two reasons: + +1. The word 'User' often implies a human being in many software systems. But sometimes the 'currently executing user' isn't a human being at all - maybe it is a 3rd-party process or remote server or daemon account. The word 'Subject' is more general and can mean 'the entity interacting with the software'. +2. The word 'Subject', because it is a general-purpose concept, is the actual term most often used in the security world. We retain that definition to be consistent. + +You can acquire the current `Subject` anywhere in your application code as shown here: + +``` java +import org.apache.shiro.subject.Subject; +import org.apache.shiro.SecurityUtils; +... +Subject currentUser = SecurityUtils.getSubject(); +``` + +Once you have a `Subject` instance, you immediately have access to 90% of everything you would ever need to do to perform security for that Subject, such as login and logout, perform role and permission checks, access their session, and more - but more about this later. The most important thing to know is that the `Subject` is your 'security-specific view' of an application 'user' and that you can essentially access this anywhere in application code to perform whatever security operations you need. + +<a name="Overview-TheSecurityManager"></a> +####The SecurityManager + +While application developers almost exclusively interact with `Subject` instances in their code, Subjects have a 'behind the scenes' counterpart that makes them work - the Shiro `SecurityManager` (note this is _not_ the same thing as the `java.lang.SecurityManager`). + +While a `Subject` instance represents security information and operations for a single user, the Shiro `SecurityManager` manages security operations for _all_ users. It is essentially the 'man behind the curtain' that manages all features in Shiro for all Subjects. Each software application that uses Shiro typically has one and only one `SecurityManager` instance. + +The `SecurityManager` is the heart of Shiroâs architecture and acts as a sort of 'umbrellaâ object that coordinates internally nested security components that form an object graph. However, once the SecurityManager and its internal object graph is configured, it is usually left alone and application developers spend almost all of their time with the `Subject` API. + +We will talk about the `SecurityManager` in detail later on, but it is important to realize that when you interact with a `Subject`, it is really the `SecurityManager` behind the scenes that does all the heavy lifting for any `Subject` security operation. This is reflected in the basic flow diagram above. + +<a name="Overview-Realms"></a> +####Realms + +The third and final core concept in Shiro is that of a Realm. A Realm acts as the âbridgeâ or âconnectorâ between Shiro and your applicationâs security data. That is, when it comes time to actually interact with security-related data like user accounts to perform authentication (login) and authorization (access control), Shiro looks up many of these things from one or more Realms configured for an application. + +In this sense a Realm is essentially a security-specific [DAO](https://en.wikipedia.org/wiki/Data_access_object): it encapsulates connection details for data sources and makes the associated data available to Shiro as needed. When configuring Shiro, you must specify at least one Realm to use for authentication and/or authorization. More than one Realm may be configured, but at least one is required. + +Shiro provides out-of-the-box Realms to connect to a number of security data sources (aka directories) such as LDAP, relational databases (JDBC), text configuration sources like INI and properties files, and more. You can plug-in your own Realm implementations to represent custom data sources if the default Realms do not meet your needs. + +Like other internal components, the Shiro `SecurityManager` manages how Realms are used to acquire security data and then represented as `Subject` instances. \ No newline at end of file
![https://cwiki.apache.org/confluence/images/icons/emoticons/smile.png"](https://cwiki.apache.org/confluence/images/icons/emoticons/smile.png"){kind=link}
