foulkon

Foulkon

Foulkon is an authorization server that allows or denies access to web resources.

This system depends on an identity provider that authenticates users. In this first version we will only implement the OIDC protocol validation. This is a scheme flow:

1. User opens a webapp (client) with a browser.
2. Client sends a request to IDP to get a token for this user.
3. Browser is redirected to IDP authentication endpoint where user uses its credentials to authenticate.
4. IDP redirects user to client. Client uses the code generated by IDP to exchange a valid OIDC token.
5. Client asks the resource provider for a specified resource using the token received by IDP.
6. Resource provider asks to AuthZ sending resource name (urn), action and OIDC token received from client. To avoid this logic there is a proxy tool that you can use to do the authorization.
7. AuthZ verify the token signature using keys from IDP.
8. AuthZ sends the resulting effect associated to resources + action + user (extracted from OIDC token).
   • If a resource or some resources are allowed, the resource provider serves the resources to the client.
   • If there isn't any resource allowed, AuthZ response will be 403 forbidden.

Installation / usage

This project generates 2 apps:

• Worker: This is the authorization server itself.
• Proxy: This transfers the requests to the authorization server (worker).

Installation/deployment docs using Go binaries or Docker:

• Worker
• Proxy

Documentation

Specification docs:

• Specification
• Use case
• Internal IAM Actions

API docs:

• User
• Group
• Policy
• Proxy Resource
• OIDC Provider
• Authorization

You can also import this Postman collection file with all API methods.

Limitations

Since validation is different in each identity provider, Foulkon needs ID Token instead of Access Token in order to check user permissions in Authorization header with type bearer. E.g.:

GET /example/resource HTTP/1.1
  Host: server.example.com
  Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAx
  IiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V8
  a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgj
  xqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWO
  LrLl0nx7RkKU8NXNHq-rvKMzqg

Development

For local development, first make sure Go is properly installed according to Go install doc (Also, include $GOBIN environment var in your $PATH). Then run next command in project root path:

$ make bootstrap

Afterwards type make test. This will run the tests. If this exits with exit status 0, then everything is working!

$ make test

To compile a development version of Foulkon, run make dev. This will put the Foulkon binaries in the $GOPATH/bin folder:

$ make dev
...
$ $GOPATH/bin/worker
$ $GOPATH/bin/proxy
...

Contribution policy

Contributions via GitHub pull requests are gladly accepted from their original author. Along with any pull requests, please state that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.

Please make sure to follow these conventions:

• For each contribution there must be a ticket (GitHub issue) with a short descriptive name, e.g. "run go imports in Makefile"
• Work should happen in a branch named "ISSUE-DESCRIPTION", e.g. "32-go-imports-in-Makefile"
• Before a PR can be merged, all commits must be squashed into one with its message made up from the ticket name and the ticket id, e.g. "better go files formatting: run go imports in Makefile (closes #32)"

Questions

If you have a question, preferably use Gitter chat. As an alternative, prepend your issue with [question].

License

This code is open source software licensed under the Apache 2.0 License.