Glow Auth – for OAuth2

Glow Auth is a gleam OAuth 2.0 helper library. See RFC6749.

Installation

This package can be added to your Gleam project:

gleam add glow_auth

and its documentation can be found at https://hexdocs.pm/glow_auth.

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Grant Types

The specification defines four grant types – authorization code, implicit, resource owner password credentials, and client credentials – as well as an extensibility mechanism for defining additional types.

Once granted an access token, it is typically included as a header in your requests to the HTTP service.

Use glow_auth#authorization_header to embed the header to your request.

Authorization Code

The authorization code is obtained by using an authorization server as an intermediary between the client and resource owner. Instead of requesting authorization directly from the resource owner, the client directs the resource owner to an authorization server (via its user-agent as defined in [RFC2616]), which in turn directs the resource owner back to the client with the authorization code.

Use glow_auth/authorize_uri to build up an authorization uri to use to redirect to.

On redirect back, you’ll receive a code that can be used to request a token.

• Use glow_auth/token_request#authorize_code to do the token request.
• Use glow_auth/access_token#decoder to decode an access token response to an Access Token.

It’s pretty common for these to have an expiry and support refresh flow.

• Use glow_auth.token_request#refresh to refresh a token.

Implicit

The implicit grant is a simplified authorization code flow optimized for clients implemented in a browser using a scripting language such as JavaScript. In the implicit flow, instead of issuing the client an authorization code, the client is issued an access token directly (as the result of the resource owner authorization). The grant type is implicit, as no intermediate credentials (such as an authorization code) are issued (and later used to obtain an access token).

Not supported.

Resource Owner Password Credentials

The resource owner password credentials (i.e., username and password) can be used directly as an authorization grant to obtain an access token. The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g., the client is part of the device operating system or a highly privileged application), and when other authorization grant types are not available (such as an authorization code).

Not supported (yet).

Client Credentials

Client credentials are used as an authorization grant typically when the client is acting on its own behalf (the client is also the resource owner) or is requesting access to protected resources based on an authorization previously arranged with the authorization server.

• Use glow_auth/token_request#client_credentials to do the token request.
• Use glow_auth/access_token#decoder to decode an access token response to an Access Token.

Refreshing

Issuing a refresh token is optional at the discretion of the authorization server. If the authorization server issues a refresh token, it is included when issuing an access token, typically also with seconds till expiry.

• Use glow_auth.token_request#refresh to refresh a token.

Concurrency Considerations

1. When receiving a code in an AuthCode flow redirect, be aware that if an auth code is used more than once, it MUST be denied, and all tokens previously issued based on it
2. When refreshing a token, typically the old access tokens are revoked.