README.md 4.08 KB
Newer Older
Snorre Magnus Davøen's avatar
Snorre Magnus Davøen committed
1 2
# clj-jwt

3 4
![clj-jwt logo](./clj-jwt.png)

Snorre Magnus Davøen's avatar
Snorre Magnus Davøen committed
5 6
A Clojure library to handle validation of JWTs.

7
```clojure
8
[no.nsd/clj-jwt "0.2.1"]
9 10
```

Snorre Magnus Davøen's avatar
Snorre Magnus Davøen committed
11 12 13 14 15 16 17
The library exposes functions to handle validation of JSON web tokens. It wraps
some of [Buddy's](https://funcool.github.io/buddy-sign/latest/) jwt signature
handling functions and uses a JWKS endpoint to fetch the public keys to use for
signature validation.

## Usage

18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
You can use the `unsign` function which wraps buddy-sign's own unsign function:

```clojure
(require '[no.nsd.clj-jwt :as clj-jwt])

(clj-jwt/unsign "https://sso-stage.nsd.no/.well-known/jwks.json" "<your-token-here>")
```

Or you can use the `resolve-key` function with the  jws backend from
buddy-auth:

```clojure
(require '[buddy.auth.backends :as backends])
(require '[no.nsd.clj-jwt :as clj-jwt])

(def auth-backend
  (backends/jws {:secret (partial clj-jwt/resolve-key "https://sso-stage.nsd.no/.well-known/jwks.json")
                 :token-name "Bearer"
                 :authfn (fn [claims] claims)
                 :on-error (fn [request err] nil)
                 :options {:alg :rs256}}))
```
Snorre Magnus Davøen's avatar
Snorre Magnus Davøen committed
40

41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
## Development

Ensure you have [Clojure installed](https://clojure.org/guides/getting_started).
Then clone project and run Clojure Tools Deps targets.  If you have rlwrap
installed you can use the `clj` command in place of `clojure`.

```bash
# Run regular old Clojure tests
clojure -Atest

# Exercise clojure specs
clojure -Apropertytest
```

You can start a REPL in the project to evaluate code. If you need an nREPL configure
a global tools deps alias in `~/.clojure/deps.edn`:

```clojure
{:aliases {:nREPL {:extra-deps  {nrepl/nrepl {:mvn/version "0.4.5"}}
                   :main-opts   ["-m" "nrepl.cmdline"]}}}
```

Then run:

```bash
clojure -AnREPL
```

### Installing 'work in progress' locally

If you are contributing code to the library you may wish to test it against a
clojure project locally to ensure everything works.

You may install your version of clj-jwt into your local m2 repository:

```bash
lein install
```

If you use clojure tools deps you can simply refer to your clj-jwt project in
the other clojure project's `deps.edn` file:

```edn
{:deps
 {clj-jwt {:local/root "/path/to/clj-jwt"}}}
```

## Making new release

You need [Leiningen installed](https://leiningen.org/#install). The
`project.clj` file specifies a `snapshot` and `release` repository. You need to
configure credentials for each of the repositories in your
`~/.lein/credentials.clj` file. Example:

```edn
{"https://nexus.nsd.no/repository/maven-snapshots/" {:username "your-nexus-user"
                                                     :password "super secret password"}
 "https://nexus.nsd.no/repository/maven-releases/" {:username "your-nexus-user"
                                                     :password "super secret password"}}
```

To make a release follow these points:

### Run tests and property tests (specs)

```bash
# Run regular old Clojure tests
clojure -Atest

# Exercise clojure specs
clojure -Apropertytest
```

### Bump version number in project.clj

There are different scenarios where you need to increment the version number
differently. The gist of it is that this library follows
[semver](https://semver.org/) with SNAPSHOT releases for test releases.

Making final release from snapshot builds:

0.2.0-SNAPSHOT -> 0.2.0

Making snapshot release from release build:

0.2.0 -> 0.3.0-SNAPSHOT

Making patch release from release build:

0.2.0 -> 0.2.1

Then run the lein deploy command:

### Run leiningen deploy

To build jar and upload to [NSD's Nexus](https://nexus.nsd.no):

```bash
lein deploy
```

### Finally commit, push and tag release

Commit the project.clj version bump, push it to the Gitlab repository, and tag
it. The tag message should describe the changes made, and the release notes can
link to the release in Nexus.

PS! It is not necessary to commit and push SNAPSHOT releases. SNAPSHOT releases
are mutable and should not be tagged in git.

Snorre Magnus Davøen's avatar
Snorre Magnus Davøen committed
151 152 153 154 155 156
## License

Copyright © 2018 NSD - NORSK SENTER FOR FORSKNINGSDATA AS

Distributed under the Eclipse Public License either version 1.0 or (at
your option) any later version.