Authority provides a simple yet flexible authentication system using OAuth.

Setting up OAuth

1. Register your application with the desired OAuth provider.

2. Obtain the client ID and client secret.

3. Set these in the environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET.

OAuth Flow

• Users will be redirected to the OAuth provider for authentication.

• Once authenticated, the provider will return an authorization code.

• This code can be exchanged for an access token, which can be used for further API requests.

Overview

Client providers are responsible for managing OAuth clients in the Authority authentication system. They represent applications that request access to user resources on behalf of the users.

Configuring Client Providers

To set up a client provider, you'll need to configure Authly config/authly.cr settings for your application. This is typically done by defining a Client Provider class that has access to the registered client data.

Create a class similar to the example below

Example:

Register the class in config/authly.cr

Example

Using Client Providers

Once configured, your application can initiate the OAuth flow by redirecting users to the provider's authorization page. Here's an example of how the flow works:

1. The user is redirected to the OAuth provider.

2. After authentication, the user is redirected back to your application with an authorization code.

3. Use this code to request an access token.

In your CLIENT application, you must use the client_id and client_secret generated by the provider

Client providers allow your application to securely interact with OAuth providers on behalf of users.

A grant is a method of acquiring an access token. Deciding which grants to implement depends on the type of client the end-user will be using, and the experience you want for your users.

Dive into the specifics of each OAuth 2 Flow implementation

About Authority Server

Authority is an OAuth 2 Server, sometimes also referred to as an OAuth 2.0 Server, OAuth Server, Authorization Server, is a software system that implements network protocol flows that allow a client software application to act on behalf of a user.

Authority is an OpenID OAuth 2.0 Server and OpenID Connect Provider written in Crystal optimized for low-latency, high throughput, and low resource consumption. Authority has a built in identity provider user login.

Authority is an open source API security for your infrastructure.

Architecture

Authority follows architecture principles that work best on container orchestration systems such as Kubernetes, CloudFoundry, OpenShift, and similar projects. While it is possible to run the Authority stack on a RaspberryPI, the integration with the Docker and Container ecosystem is best documented and supported.

Authority's architecture is designed along several guiding principles:

• Minimal dependencies (no system dependencies; might need a database backend)

• Runs everywhere (Linux, macOS, FreeBSD, Windows; AMD64, i386, ARMv5, ...)

• Scales without effort (no memcached, etcd, required, ...)

• Minimize room for human and network errors

OAuth 2 Implementations

Implementing and using OAuth2 without understanding the whole specification is challenging and prone to errors, even when SDKs are being used. The primary goal of Authority is to make OAuth 2.0 and OpenID Connect 1.0 better accessible.

The Authority implements five grants for acquiring an access token:

• Authorization code Grant

• Implicit Grant

• Resource owner credentials grant

• Client credentials grant

Explore the implementations

The following RFCs are implemented:

Why Authority is Different​

Authority differentiates itself in the following key areas:

• Everything is developed and licensed under Open Source Principles, allowing you to participate, collaborate, and understand the inner workings of Authority.

• You can bring your own UI, in the programming language of your choosing, with the user experience that you like.

• From designing Identity Schemas, to webhooks, to advanced configuration options - Authority is fully customizable.

Authorization Flow

You can modify the default behavior of the Authority authentication system by extending the authentication logic.

Custom OAuth Providers

To add a custom OAuth provider, modify the OAuth::Client configuration in the src/auth.cr file:

OAuth::Client.new do |config|
  config.client_id = ENV["CUSTOM_OAUTH_CLIENT_ID"]
  config.client_secret = ENV["CUSTOM_OAUTH_CLIENT_SECRET"]
end

This allows you to connect to other OAuth providers or implement custom authentication logic.

Prerequisites

• Crystal language installed. Follow the official Crystal installation guide.

• PostgreSQL or another supported database.

• Docker (if using Docker setup).

Steps

1. Clone the repository:

2. Install dependencies:

3. Set up the database:

4. Configure environment variables in .env.local:

Or using Docker:

OAuth 1.0 requires that the protected resources endpoints have access to the client credentials in order to validate the request. This breaks the typical architecture of most large providers in which a centralized authorization server is used for issuing credentials, and a separate server is used for handling API calls. Because OAuth 1.0 requires the use of the client credentials to verify the signatures, it makes this separation very hard.

OAuth 2.0 addresses this by using the client credentials only when the application obtains authorization from the user. After the credentials are used in the authorization step, only the resulting access token is used when making API calls. This means the API servers do not need to know about the client credentials since they can validate access tokens themselves.

• Authorization code grant

• Client credentials grant

• Implicit grant

• Resource owner credentials grant

• Refresh token grant

• OpenID Connect

• PKCE

• JSON Web Tokens

• Device Code grant

• Token Introspection

• Token Revocation

• Opaque Tokens

• Client SDKs

• Account recovery & verification

• MFA

• Permission and Role Management

• Social Signin

Authority exposes several API endpoints for authentication. Below are some key endpoints:

• POST /auth/login: Authenticate a user and obtain a token.

• GET /auth/user: Retrieve authenticated user details.

• POST /auth/logout: Log out a user.

Each endpoint accepts and returns JSON data. Ensure that you include the correct OAuth token in the Authorization header for protected routes.

The Authority project includes several important configuration files located in the src/config directory. These files define settings for key components of the application, including sessions, authentication, and the overall system behavior.

Available Configuration Files

1. session.cr

The session.cr file handles session management for the application. Sessions are crucial for maintaining user state between requests, especially in authentication systems.

Key settings:

• Session duration: Define how long a session should remain active before expiring.

• Storage options: Configure where session data is stored (e.g., in-memory or database-backed).

You can adjust session behavior based on your requirements by modifying this file.

2. authly.cr

The authly.cr file is responsible for authentication-related settings. This includes OAuth configuration and other authentication logic.

Key settings:

• OAuth client configuration: Define client IDs, secrets, and other OAuth-specific settings.

• Authentication flows: Customize how the system handles different types of authentication (e.g., token-based or session-based).

3. clear.cr

The clear.cr file likely manages caching and clearing of session data or other temporary data. This file ensures that outdated session data or cache entries are purged efficiently.

Key settings:

• Cache expiration: Define when cached data should be invalidated.

• Manual clearing options: Set up specific points where data is cleared to optimize performance.

4. authority.cr

The authority.cr file contains the main configurations for the Authority authentication system. This file ties together various authentication and authorization components.

Key settings:

• General system settings: Configure global behavior for the Authority system.

• Custom provider options: Define how different authentication providers are integrated with the system.

Customizing Configuration

To customize any of these settings, simply open the corresponding configuration file in the src/config directory and adjust the necessary parameters. Be sure to restart the application after making changes to ensure that the new configurations are applied.

This project requires

• Crystal Language - find the installation instructions here https://crystal-lang.org/install/

• Git - https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

• PostgreSQL - https://www.postgresql.org/docs/current/tutorial-install.html

• Docker and Docker-Compose -

• Geckodriver - Needed for specs

This tutorial walks you through a quick setup of Authority, a PostgreSQL instance, and a simple User Login & Consent App based on Docker Compose. You need to have the latest Docker and Docker Compose version installed.

Dockerfile

Authority project contains a simple Dockerfile that compiles and builds a simple docker image with little to no dependencies.

FROM crystallang/crystal:latest-alpine as source
WORKDIR /opt/app
COPY . /opt/app
RUN shards install
RUN crystal build --release --static ./src/server.cr -o ./server
CMD ["crystal", "spec"]

FROM alpine:latest  
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=source /opt/app/server .
COPY --from=source /opt/app/public ./public
CMD ["./server"]

Docker-Compose

To start using Authority run the following command

Common Issues

• Invalid OAuth Token: Ensure the token has not expired and is correctly included in the Authorization header.

• Database Connection Failed: Check that the DATABASE_URL environment variable is set correctly.

Check the logs for detailed error messages and follow standard Crystal debugging practices to resolve issues.

Overview

Owner providers in the Authority system represent the resource owners—typically the users who own the data or resources being accessed. They play a crucial role in controlling access to their resources.

Configuring Owner Providers

To configure an owner provider, you need to establish ownership models in your application. This usually involves mapping user records to resources that they own.

Example Configuration

In your database schema, make sure that resources have an owner_id field that corresponds to the user who owns the resource.

Using Owner Providers

Once the ownership structure is in place, you can enforce access control rules by checking whether the currently authenticated user is the owner of the resource they are trying to access.

Example in Crystal:

Owner providers help implement fine-grained access control mechanisms, ensuring that users can only access the resources they own.

You can customize the database table and fields of your Authority server by simply modifying the migration files found under db/migrations.

Clients Migration File

The Managed UI implements screens such as login, registration, account recovery, account setting, and account verification. This allows for fast adoption of Authority.

Contrary to other vendors, Authority allows you to implement your own UI by offering simple HTML templates. You can change the look of Authority signin and authorize HTML pages.

The Public directory

The public directory contains all the front-end CSS and HTML-related files that compose the user interface for Authority. These are small easy to understand files that are clearly named for easy adoption.

Just edit the ./public/templates/signin.html and ./public/templates/authorize.html

HTML (jinja) Templates

A template contains variables and/or expressions, which get replaced with values when a template is rendered; and tags, which control the logic of the template.

Below is a minimal template that illustrates a few basics using the default Jinja configuration. We will cover the details later in this document:

This flow is seen on devices such as smart TVs, media consoles, picture frames, printers, or hardware video encoders. In this flow, the device instructs the user to open a URL on a secondary device such as a smartphone or computer in order to complete the authorization. There is no communication channel required between the user’s two devices.

Authorization Request

First, the client makes a request to the authorization server to request the device code.

All server settings are defined using environment variables

It is intended to be used for user-agent-based clients (e.g. single page web apps) that can’t keep a client secret because all of the application code and storage are easily accessible.

Secondly, instead of the authorization server returning an authorization code that is exchanged for an access token, the authorization server returns an access token.

The Flow

The client will redirect the user to the authorization server with the following parameters in the query string:

• response_type with the value token

• client_id with the client identifier

• redirect_uri with the client redirect URI. This parameter is optional, but if not sent the user will be redirected to a pre-registered redirect URI.

• scope a space delimited list of scopes

• state with a token. This parameter is optional but highly recommended. You should store the value of the CSRF token in the user’s session to be validated when they return.

All of these parameters will be validated by the authorization server.

The user will then be asked to sign in to the authorization server and approve the client.

If the user approves the client they will be redirected back to the authorization server with the following parameters in the query string

Self-Encoded Access Tokens

Self-encoded tokens provide a way to avoid storing tokens in a database by encoding all of the necessary information in the token string itself. The main benefit of this is that API servers are able to verify access tokens without doing a database lookup on every API request, making the API much more easily scalable.

The benefit of OAuth 2.0 Bearer Tokens is that applications don’t need to be aware of how you’ve decided to implement access tokens in your service. This means it’s possible to change your implementation later without affecting clients.

A common technique for this is using the (JWS) standard to handle encoding, decoding and verification of tokens. The (JWT) specification defines some terms you can use in the JWS, as well as defines some timestamp terms to determine whether a token is valid. We’ll use a JWT library in this example, since it provides built-in handling of expiration.

As a refresher here is a quick glossary of OAuth terms (taken from the core spec):

• Resource owner (a.k.a. the User) - An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.

• Resource server (a.k.a. the API server) - The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

• Client - An application making protected resource requests on behalf of the resource owner and with its authorization. The term client does not imply any particular implementation characteristics (e.g. whether the application executes on a server, a desktop, or other devices).

• Authorization server - The server issues access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

Access Token Owner

An access token represents permission granted to a client to access some protected resources.

If you authorize a machine to access resources and don’t require user permission to access said resources, you should implement the client credentials grant.

Clients

Whether or not the client is capable of keeping a secret will depend on which grant the client should use.

If the client is a web application with a server-side component, you should implement the authorization code grant.

If the client is a web application that has runs entirely on the front end (e.g., a single page web application), you should implement the password grant for first -arty clients and the implicit grant for a third party clients.

If the client is a native application such as a mobile app, you should implement the password grant.

First-Party and Third-Party Clients

A first-party client is a client that you trust enough to handle the end user’s authorization credentials. For example, Spotify’s iPhone app is owned and developed by Spotify; therefore, they implicitly trust it.

A third-party client is a client that you don’t trust.

The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user. This is typically used by clients to access resources about themselves rather than to access a user's resources.

Example

The following is an example authorization code grant the service would receive.

Client Credentials

POST https://app.com/token

In some cases, applications may need an access token to act on behalf of themselves rather than a user. For example, the service may provide a way for the application to update their own information such as their website URL or icon, or they may wish to get statistics about the users of the app. In this case, applications need a way to get an access token for their own account, outside the context of any specific user. OAuth provides the client_credentials grant type for this purpose.

Headers

Request Body

eWhen you initially received the access token, it may have included a refresh token as well as an expiration time like in the example below.

The presence of the refresh token means that the access token will expire and you’ll be able to get a new one without the user’s interaction.

The “expires” value is the number of seconds that the access token will be valid. It’s up to the service you’re using to decide how long access tokens will be valid, and may depend on the application or the organization’s own policies. You can use this to preemptively refresh your access tokens instead of waiting for a request with an expired token to fail.

If you make an API request and the token has expired already, you’ll get back a response indicating as such. You can check for this specific error message, and then refresh the token and try the request again.

If you’re using a JSON-based API, then it will likely return a JSON error response with the invalid_token error. In any case, the WWW-Authenticate header will also have the invalid_token error.

When your code recognizes this specific error, it can then make a request to the token endpoint using the refresh token it previously received, and will get back a new access token it can use to retry the original request.

To use the refresh token, make a POST request to the service’s token endpoint with grant_type=refresh_token, and include the refresh token as well as the client credentials.

Refresh Access Token

POST https::/app.com/token

The refresh token, make a POST request to the service’s token endpoint with grant_type=refresh_token, and include the refresh token as well as the client credentials.

Headers

Request Body

Authority is an authentication solution built with the Crystal programming language. It offers robust authentication features, including OAuth grants and customizable authentication logic. The following documentation will guide you through the installation, configuration, and usage of the Authority project.

The authorization code grant is used when an application exchanges an authorization code for an access token. After the user returns to the application via the redirect URL, the application will get the authorization code from the URL and use it to request an access token. This request will be made to the token endpoint.

The Flow (Part One)

The client will redirect the user to the authorization server with the following parameters in the query string:

Authorization Code

GET https://authorization-server.com/authorize

The client will redirect the user to the authorization server with the following parameters in the query string:

Query Parameters

The parameters will be validated by the authorization server.

User Authorization Prompt

The user will then be asked to sign in to the authorization server and approve the client.

The user sees the authorization prompt

If the user approves the client they will be redirected from the authorization server back to the client (specifically to the redirect URI) with the following parameters in the query string:

• code with the authorization code

• state with the state parameter sent in the original request. You should compare this value with the value stored in the user’s session to ensure the authorization code obtained is in response to requests made by this client rather than another client application.

PKCE Extension

The Proof Key for Code Exchange (PKCE, pronounced pixie) extension describes a technique for public clients to mitigate the threat of having the authorization code intercepted. The technique involves the client first creating a secret, and then using that secret again when exchanging the authorization code for an access token. This way if the code is intercepted, it will not be useful since the token request relies on the initial secret.

Once the app has generated the code verifier, it uses that to create the code challenge. For devices that can perform a SHA256 hash, the code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier. Clients that do not have the ability to perform a SHA256 hash are permitted to use the plain code verifier string as the challenge.

Now that the client has a code challenge string, it includes that and a parameter that indicates which method was used to generate the challenge (plain or S256) along with the standard parameters of the authorization request. This means a complete authorization request will include the following parameters.

The Flow (Part Two)

Exchange the authorization code for an access token

To exchange the authorization code for an access token, the app makes a POST request to the service’s token endpoint. The request will have the following parameters.

Creates an Access Token

POST https://my-auth-server.com/token

The server exchanges the authorization code for an access token by making a POST request to the token endpoint.

Headers

Request Body

OAuth Security

Up until 2019, the OAuth 2.0 spec only recommended using the extension for mobile and JavaScript apps. The latest OAuth Security BCP now recommends using PKCE also for server-side apps, as it provides some additional benefits there as well. It is likely to take some time before common OAuth services adapt to this new recommendation, but if you’re building a server from scratch you should definitely support PKCE for all types of clients.

The Password grant is used when the application exchanges the user’s username and password for an access token.

A common use for this grant type is to enable password logins for your service’s own apps. Users won’t be surprised to log in to the service’s website or native application using their username and password, but third-party apps should never be allowed to ask the user for their password.

Example

The following is an example password grant the service would receive.

See for details on the parameters to return when generating an access token or responding to errors.

Successful Response

If the request for an access token is valid, the authorization server needs to generate an access token (and optional refresh token) and return these to the client, typically along with some additional properties about the authorization.

For example, a successful token response may look like the following:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
 
{
  "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
  "scope":"create"
}

Access Tokens

The format for OAuth 2.0 Bearer tokens is actually described in a separate spec, . There is no defined structure for the token required by the spec, so you can generate a string and implement tokens however you want. The valid characters in a bearer token are alphanumeric, and the following punctuation characters:

OpenID Connect provides user identity and authentication on top of the OAuth 2.0 framework. You can use OpenID Connect to establish a login session, and use OAuth to access protected resources.

You can request both an ID token and access token in the same flow in order to both authenticate the user as well as obtain authorization to access a protected resource.

OpenID Connect is maintained by the OpenID Foundation. The core OpenID Connect spec, as well as many extensions, can be read in full on https://openid.net/connect/.

The OpenID Connect Debugger is a fantastic resource to help you build OpenID Connect requests and walk through the flows. Additionally, the OAuth 2.0 Playground provides a walkthrough of the OpenID Connect flow against a live server.

When a developer comes to your website, they will need a way to create a new application and obtain credentials. Typically you will have them create a developer account, or create an account on behalf of their organization, before they can create an application.

While the OAuth 2.0 spec doesn’t require you to collect any application information in particular before granting credentials, most services collect basic information about an app, such as the app name and an icon, before issuing the client_id and client_secret. It is, however, important that you require the developer to register one or more redirect URLs for the application for security purposes. This is explained in more detail in Redirect URLs.

Typically services collect information about an application such as:

• Application name

• An icon for the application

• URL to the application’s home page

• A short description of the application

• A link to the application’s privacy policy

• A list of redirect URLs

The Client ID and Secret

Client ID

The client_id is a public identifier for apps. Even though it’s public, it’s best that it isn’t guessable by third parties, so many implementations use something like a 32-character hex string. It must also be unique across all clients that the authorization server handles. If the client ID is guessable, it makes it slightly easier to craft phishing attacks against arbitrary applications.

Client Secret

The client_secret is a secret known only to the application and the authorization server. It must be sufficiently random to not be guessable, which means you should avoid using common UUID libraries which often take into account the timestamp or MAC address of the server generating it. A great way to generate a secure secret is to use a cryptographically-secure library to generate a 256-bit value and convert it to a hexadecimal representation.

The project specifications can be found in the specs directory. Use the directory to get an idea of the project capabilities and configuration.

Running Specs

If you have all the requirements installed, running the specs should be fairly simple. Run the following commands to run the specs locally

shards build server
crystal specs

Headless Mode

Specs run using the Flux shard, this allows for browser testing. Currently, the configuration is set to run headless by default, which means that you will not see the browser interactions, if you wish to change this behavior simply remove the `-headless` parameter for the spec/flows files

Security is a critical aspect of the Authority authentication system. Below are some key considerations:

• Token Management: Ensure that OAuth tokens are stored securely and are not exposed to unauthorized users.

• Access Control: Implement proper access control mechanisms to ensure that only authorized users can access sensitive data.

• Encryption: Always use HTTPS to encrypt communication between the client and the server.

This section documents all the available API endpoints in the Authority project. Each endpoint serves a specific purpose, such as managing OAuth clients, handling user sessions, or authorizing users.

1. Clients Endpoints

The clients endpoints manage OAuth clients that represent applications interacting with the Authority system.

• POST /clients: Create a new OAuth client.

  Example Request:

  Example Response:

• GET /clients: Retrieve a list of registered OAuth clients.

  Example Response:

2. Owner Endpoints

The owner endpoints manage resource owners, allowing the Authority system to verify and manage access to resources owned by users.

• GET /owner: Retrieve information about the authenticated resource owner.

  Example Response:

3. Sessions Endpoints

The sessions endpoints manage user sessions, including login and logout functionality.

• POST /sessions/login: Authenticate a user and create a session.

  Example Request:

  Example Response:

• POST /sessions/logout: Log out the authenticated user and invalidate the session.

  Example Response:

4. Authorize Endpoints

The authorize endpoints manage the OAuth authorization flow.

• GET /authorize: Redirect users to the OAuth provider for authorization.

  • Example Response: Redirects the user to the OAuth provider's login page.

• POST /authorize: Handle the authorization code returned by the OAuth provider and exchange it for an access token.

  Example Request:

5. Device Endpoints

The device endpoints manage device-specific interactions, such as registering or authenticating devices.

• POST /device/register: Register a new device.

  Example Request:

  Example Response:

6. Access Token Endpoints

The access_token endpoints handle the management of access tokens, including issuing, refreshing, and revoking tokens.

• POST /access_token: Exchange an authorization code for an access token.

  Example Request:

  Example Response:

• POST /access_token/revoke: Revoke an access token.

  Example Request:

  Example Response:

7. Health Check

The health_check.cr endpoint is used to check the health of the Authority service.

• GET /health_check: Returns the status of the service.

  Example Response: