search

nerdErg / grails-shiro

Grails 3 & 4 Shiro plugin
Other
7 stars 8 forks source link

readme

= Grails Shiro plugin :icons: font :iconfont-cdn: //cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css :stylesdir: docs/resources/style/ :stylesheet: asciidoctor.css :description: Grails shiro plugin :keywords: documentation, Grails, Shiro, 3.3.10, 4.0.0, 1.4.1 :links: :sectlinks: :toc: left :toclevels: 2 :toc-class: toc2 :release: 5.0.0 :working-versions: 5.0.0, Apache Shiro 2.0.1 :released-versions: 5.0.0, Apache Shiro 2.0.1

image:https://travis-ci.org/nerdErg/grails-shiro.svg?branch=master["Build Status", link="https://travis-ci.org/nerdErg/grails-shiro"]

== Versions

This project was derived from the Grails 2.x version (https://github.com/pledbrook/grails-shiro).

We pretty much re-wrote the plugin for Grails 3 & 4 and to simplify the use, improve the documentation and make it easier to maintain. There are lots of changes please check out the https://github.com/nerdErg/grails-shiro/blob/master/docs/Guide.adoc[Guide] in the docs directory.

=== Numbering

In general the version number is following the Grails major version it supports, then release. e.g.

[subs="attributes"]

5.0.0 = Grails 5 plugin release 0 3.4 = Grails 3 plugin release 4 4.5.9 = Grails 4 plugin release 5.9

=== Maintenance

We are working on a Grails 6 plugin.

The Grails 5 plugin will be maintained to match shiro releases where possible and bugs fixed. We will add some extra AD LDAP support too.

=== Documentation and Source

In general the documentation applies to all versions of the plugin. Source code including specific documentation for older Grails versions can be found in the Branches.

== Installation

To install, add this to your build.gradle dependencies for Grails 5:

[subs="attributes"]

implementation "org.nerderg.plugins:grails-shiro:{release}"

//include the shiro dependency, required in Gradle 5+ ['ehcache', 'core', 'spring', 'web'].each { pkg -> implementation("org.apache.shiro:shiro-$pkg:2.0.1") { exclude module: 'ejb' exclude module: 'jsf-api' exclude module: 'servlet-api' exclude module: 'jsp-api' exclude module: 'jstl' exclude module: 'jms' exclude module: 'connector-api' exclude module: 'ehcache-core' exclude module: 'slf4j-api' exclude module: 'commons-logging' } }

and this for Grails 4:

[subs="attributes"]

compile "org.grails.plugins:grails-shiro:4.4"

and this for Grails 3:

[subs="attributes"]

compile "org.grails.plugins:grails-shiro:3.4"

== Getting started

If you're implementing your security from scratch, then you can install grails-shiro as above and typing

grails shiro-quick-start

See: https://github.com/nerdErg/grails-shiro/blob/master/docs/Guide.adoc#shiro-quick-start[grails shiro-quick-start].

This will create a ShiroWildcardDbRealm in your grails-app/realms directory and make a ShiroUser and ShiroRole domain class. It will also create an AuthController to let you log in. Check out https://github.com/nerdErg/grails-shiro/blob/master/docs/Guide.adoc#wildcard-db-realm[Wildcard DB Realm] for how you might populate a couple of users using Boostrap.groovy.

Now, to Control access to a Controller add an Interceptor for that controller using

grails create-shiro-controller-interceptor MyController

See: https://github.com/nerdErg/grails-shiro/blob/master/docs/Guide.adoc#create-shiro-controller-interceptor[ create-shiro-controller-interceptor] which will add https://github.com/nerdErg/grails-shiro/blob/master/docs/Guide.adoc#permission-string-conventions[access control by convention].

== Version change log

=== version 5.0.0

WARNING: you now need to include apache shiro in your build.gradle due to the newer versions of Gradle not pulling in transitive deps. Quick Fix below.

[source,groovy] .build.gradle

dependencies { ... // add this to dependencies to get shiro depenedencies ['ehcache', 'core', 'spring', 'web'].each { pkg -> implementation("org.apache.shiro:shiro-$pkg:$shiroVersion") { exclude module: 'ejb' exclude module: 'jsf-api' exclude module: 'servlet-api' exclude module: 'jsp-api' exclude module: 'jstl' exclude module: 'jms' exclude module: 'connector-api' exclude module: 'ehcache-core' exclude module: 'slf4j-api' exclude module: 'commons-logging' } } }

=== version 4.5.8

=== version 4.4

=== version 3.3 & 4.3

WARNING: This introduces a small breaking change. Annotations now use the login and unauthorized settings not URL Mappings to set where they redirect to.

=== version 4.2

=== version 4.1

=== version 3.1

=== version 3.0

== Building from source

To build the plugin yourself and install it from this repo:

  1. clone or fork this repo to your machine
  2. run gradle publishToMavenLocal and that will build, test, install it to your local maven repo (~/.m2)
  3. profit!

== Publishing

Refer to https://grails.org/blog/2021-04-07-publish-grails-plugin-to-maven-central.html

If you have the signing and repository credentials, you can run:

./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository

But you should publish to staging and check everything first.

== Kudos

Thank you to everyone who provides feedback!