libauth/README.md

99 lines
2.2 KiB
Markdown
Raw Normal View History

2022-05-06 00:14:05 +00:00
# [libauth](https://git.rootprojects.org/root/libauth)
2022-05-06 00:11:08 +00:00
2022-05-09 19:35:47 +00:00
LibAuth for Go - A modern authentication framework that feels as light as a
library.
2022-05-06 00:11:08 +00:00
[![godoc_button]][godoc]
[godoc]: https://pkg.go.dev/git.rootprojects.org/root/libauth?tab=versions
[godoc_button]: https://godoc.org/git.rootprojects.org/root/libauth?status.svg
## Example Usage
How to verify a valid, trusted token as `chi` middleware:
```go
package main
import (
"net/http"
"github.com/go-chi/chi/v5"
"git.rootprojects.org/root/keypairs/keyfetch"
"git.rootprojects.org/root/libauth"
"git.rootprojects.org/root/libauth/chiauth"
)
func main() {
r := chi.NewRouter()
2022-05-09 19:35:47 +00:00
whitelist, err := keyfetch.NewWhitelist([]string{"https://therootcompany.github.io/libauth/"})
2022-05-06 00:11:08 +00:00
if nil != err {
panic(err)
}
tokenVerifier := chiauth.NewTokenVerifier(chiauth.VerificationParams{
Issuers: whitelist,
Optional: false,
})
r.Use(tokenVerifier)
r.Post("/api/users/profile", func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
jws, ok := ctx.Value(chiauth.JWSKey).(*libauth.JWS)
if !ok || !jws.Trusted {
http.Error(w, "Unauthorized", http.StatusUnauthorized)
2022-05-06 00:15:02 +00:00
return
2022-05-06 00:11:08 +00:00
}
userID := jws.Claims["sub"].(string)
// ...
})
// ...
}
```
2022-05-09 19:35:47 +00:00
How to create a demo token with [keypairs][https://webinstall.dev/keypairs]:
```bash
my_key='./examples/privkey.ec.jwk.json'
my_claims='{
"iss": "https://therootcompany.github.io/libauth/",
"sub": "1",
"email_verified": false,
"email": "jo@example.com"
}'
keypairs sign \
--exp 1h \
"${my_key}" \
"${my_claims}" \
> jwt.txt
2> jws.json
```
2022-05-06 00:11:08 +00:00
How to pass an auth token:
```bash
2022-05-09 19:35:47 +00:00
pushd ./examples
go run ./server.go
```
```bash
my_token="$(cat ./examples/jwt.txt)"
2022-05-06 00:11:08 +00:00
curl -X POST http://localhost:3000/api/users/profile \
2022-05-09 19:35:47 +00:00
-H "Authorization: Bearer ${my_token}" \
2022-05-06 00:11:08 +00:00
-H 'Content-Type: application/json' \
2022-05-09 19:35:47 +00:00
--data-binary '{ "foo": "bar" }'
2022-05-06 00:11:08 +00:00
```
2022-05-09 19:35:47 +00:00
## Example OIDC Discovery URLs
- Demo:
<https://therootcompany.github.io/libauth/.well-known/openid-configuration>
- Auth0: <https://example.auth0.com/.well-known/openid-configuration>
- Okta: <https://example.okta.com/.well-known/openid-configuration>
- Google: <https://accounts.google.com/.well-known/openid-configuration>