The security first OAuth2 & OpenID Connect framework for Go. Built simple, powerful and extensible. This library implements peer-reviewed IETF RFC6749, counterfeits weaknesses covered in peer-reviewed IETF RFC6819 and countermeasures various database attack scenarios, keeping your application safe when that hacker penetrates or leaks your database. OpenID Connect is implemented according to OpenID Connect Core 1.0 incorporating errata set 1 and includes all flows: code, implicit, hybrid.

This library considered and implemented:

• The OAuth 2.0 Authorization Framework
• OAuth 2.0 Multiple Response Type Encoding Practices
• OAuth 2.0 Threat Model and Security Considerations
• Proof Key for Code Exchange by OAuth Public Clients
• OAuth 2.0 for Native Apps
• OpenID Connect Core 1.0
• OAuth 2.0 Pushed Authorization Request

OAuth2 and OpenID Connect are difficult protocols. If you want quick wins, we strongly encourage you to look at Hydra. Hydra is a secure, high performance, cloud native OAuth2 and OpenID Connect service that integrates with every authentication method imaginable and is built on top of Fosite.

Table of Contents

• Motivation
• API Stability
• Example
• A word on quality
• A word on security
• A word on extensibility
• Installation
• Documentation
• Scopes
  • fosite.WildcardScopeStrategy
  • fosite.HierarchicScopeStrategy
• Quickstart
• Code Examples
• Example Storage Implementation
• Extensible handlers
• JWT Introspection
• Contribute
• Refresh mock objects
• Hall of Fame

Motivation

Fosite was written because our OAuth2 and OpenID Connect service Hydra required a secure and extensible OAuth2 library. We had to realize that nothing matching our requirements was out there, so we decided to build it ourselves.

API Stability

The core public API is almost stable as most changes will only touch the inner workings.

We strongly encourage vendoring fosite using dep or comparable tools.

Example

The example does not have nice visuals but it should give you an idea of what you can do with Fosite and a few lines of code.

You can run this minimalistic example by doing

go get github.com/ory/fosite-example
cd $GOPATH/src/github.com/ory/fosite-example
dep ensure
go install github.com/ory/fosite-example
fosite-example

There should be a server listening on localhost:3846. You can check out the example's source code here.

A word on quality

We tried to set up as many tests as possible and test for as many cases covered in the RFCs as possible. But we are only human. Please, feel free to add tests for the various cases defined in the OAuth2 RFCs 6749 and 6819 or any other cases that improve the tests.

Everyone writing an RFC conform test that breaks with the current implementation, will receive a place in the Hall of Fame!

A word on security

Please be aware that Fosite only secures parts of your server side security. You still need to secure your apps and clients, keep your tokens safe, prevent CSRF attacks, ensure database security, use valid and strong TLS certificates and much more. If you need any help or advice feel free to contact our security staff through our website!

We have given the various specifications, especially OAuth 2.0 Threat Model and Security Considerations, a very close look and included everything we thought was in the scope of this framework. Here is a complete list of things we implemented in Fosite:

• No Cleartext Storage of Credentials
• Encryption of Credentials
• Use Short Expiration Time
• Limit Number of Usages or One-Time Usage
• Bind Token to Client id
• Automatic Revocation of Derived Tokens If Abuse Is Detected
• Binding of Refresh Token to "client_id"
• Refresh Token Rotation
• Revocation of Refresh Tokens
• Validate Pre-Registered "redirect_uri"
• Binding of Authorization "code" to "client_id"
• Binding of Authorization "code" to "redirect_uri"
• Opaque access tokens
• Opaque refresh tokens
• Ensure Confidentiality of Requests
• Use of Asymmetric Cryptography Fosite ensures that redirect URIs use https except localhost but you need to implement TLS for the token and auth endpoints yourself.

Additionally, we added these safeguards:

• Enforcing random states: Without a random-looking state or OpenID Connect nonce the request will fail.
• Advanced Token Validation: Tokens are layouted as <key>.<signature> where <signature> is created using HMAC-SHA256 using a global secret. This is what a token can look like: /tgBeUhWlAT8tM8Bhmnx+Amf8rOYOUhrDi3pGzmjP7c=.BiV/Yhma+5moTP46anxMT6cWW8gz5R5vpC9RbpwSDdM=

Sections below Section 5 that are not covered in the list above should be reviewed by you. If you think that a specific section should be something that is covered in Fosite, feel free to create an issue. Please be aware that OpenID Connect requires specific knowledge of the identity provider, which is why Fosite only implements core requirements and most things must be implemented by you (for example prompt, max_age, ui_locales, id_token_hint, user authentication, session management, ...).

It is strongly encouraged to use the handlers shipped with Fosite as they follow the specs and are well tested.

A word on extensibility

Fosite is extensible ... because OAuth2 is an extensible and flexible framework. Fosite let's you register custom token and authorize endpoint handlers with the security that the requests have been validated against the OAuth2 specs beforehand. You can easily extend Fosite's capabilities. For example, if you want to provide OpenID Connect on top of your OAuth2 stack, that's no problem. Or custom assertions, what ever you like and as long as it is secure. ;)

Installation

Go 1.11+ must be installed on your system and it is required that you have set up your GOPATH environment variable.

go get -u github.com/ory/fosite/...

We recommend to use dep to mitigate compatibility breaks that come with new api versions.

Documentation

There is an API documentation available at godoc.org/ory/fosite.

Scopes

Fosite has three strategies for matching scopes. You can replace the default scope strategy if you need a custom one by implementing fosite.ScopeStrategy.

Using the composer, setting a strategy is easy:

import "github.com/ory/fosite"

var config = &fosite.Config{
ScopeStrategy: fosite.HierarchicScopeStrategy,
}

Note: To issue refresh tokens with any of the grants, you need to include the offline scope in the OAuth2 request. This can be modified by the RefreshTokenScopes compose configuration. When set to an empty array, all grants will issue refresh tokens.

fosite.WildcardScopeStrategy

This is the default strategy, and the safest one. It is best explained by looking at some examples:

• users.* matches users.read
• users.* matches users.read.foo
• users.read matches users.read
• users does not match users.read
• users.read.* does not match users.read
• users.*.* does not match users.read
• users.*.* matches users.read.own
• users.*.* matches users.read.own.other
• users.read.* matches users.read.own
• users.read.* matches users.read.own.other
• users.write.* does not match users.read.own
• users.*.bar matches users.baz.bar
• users.*.bar does not users.baz.baz.bar

To request users.*, a client must have exactly users.* as granted scope.

fosite.ExactScopeStrategy

This strategy is searching only for exact matches. It returns true iff the scope is granted.

fosite.HierarchicScopeStrategy

This strategy is deprecated, use it with care. Again, it is best explained by looking at some examples:

• users matches users
• users matches users.read
• users matches users.read.own
• users.read matches users.read
• users.read matches users.read.own
• users.read does not match users.write
• users.read does not match users.write.own

Globalization

Fosite does not natively carry translations for error messages and hints, but offers an interface that allows the consumer to define catalog bundles and an implementation to translate. This is available through the MessageCatalog interface. The functions defined are self-explanatory. The DefaultMessageCatalog illustrates this. Compose config has been extended to take in an instance of the MessageCatalog.

Building translated files

There are three possible "message key" types:

1. Value of RFC6749Error.ErrorField: This is a string like invalid_request and correlates to most errors produced by Fosite.
2. Hint identifier passed into RFC6749Error.WithHintIDOrDefaultf: This func is not used extensively in Fosite but, in time, most WithHint and WithHintf will be replaced with this function.
3. Free text string format passed into RFC6749Error.WithHint and RFC6749Error.WithHintf: This function is used in Fosite and Hydra extensively and any message catalog implementation can use the format string parameter as the message key.

An example of a message catalog can be seen in the i18n_test.go.

Generating the en messages file

This is a WIP at the moment, but effectively any scripting language can be used to generate this. It would need to traverse all files in the source code and extract the possible message identifiers based on the different message key types.

Quickstart

Instantiating fosite by hand can be painful. Therefore we created a few convenience helpers available through the compose package. It is strongly encouraged to use these well tested composers.

In this very basic example, we will instantiate fosite with all OpenID Connect and OAuth2 handlers enabled. Please refer to the example app for more details.

This little code snippet sets up a full-blown OAuth2 and OpenID Connect example.

```go package main

import "github.com/ory/fosite" import "github.com/ory/fosite/compose" import "github.com/ory/fosite/storage"

// This is the example storage that contains: // * an OAuth2 Client with id "my-client" and secrets "foobar" and "foobaz" capable of all oauth2 and open id connect grant and response types. // * a User for the resource owner password credentials grant type with username "peter" and password "secret". // // You will most likely replace this with your own logic once you set up a real world application. var storage = storage.NewExampleStore()

// This secret is being used to sign access and refresh tokens as well as // authorization codes. It must be exactly 32 bytes long. var secret = []byte("my super secret signing password")

privateKey, err := rsa.GenerateKey(rand.Reader, 2048) if err != nil { panic("unable to create private key") }

// check the api docs of fosite.Con