flwr_oauth2

This module implements functions and types for RFC6749. It offers types for all the major OAuth 2.0 grant types and functions to create the correct HTTP requests for those grant types. Furthermore, it offers functions to generate redirect URIs for the Authorization Code Grant Type and the Implicit Grant Type.

It also supports RFC7636, which adds the Proof Key for Code Exchange to the Authorization Code Grant.

Types

AccessTokenResponse

</>

This type is returned by this module for a parsed access token response.

pub type AccessTokenResponse {
  AccessTokenResponse(
    access_token: String,
    token_type: String,
    expires_in: option.Option(Int),
    refresh_token: option.Option(String),
    scope: List(String),
  )
}

Constructors

```
AccessTokenResponse(
  access_token: String,
  token_type: String,
  expires_in: option.Option(Int),
  refresh_token: option.Option(String),
  scope: List(String),
)
```
If the access token request was successful a AccessTokenResponse is returned. it contains the access token, its type, the time when it will expire, a refresh token if present, and the final scope.

AuthorizationSetter

</>

Type for functions that can set the authorization part of a request. Can be used to customize how authorization is applied to an OAuth request.

pub type AuthorizationSetter {
  AuthorizationSetter(
    setter: fn(request.Request(List(#(String, String)))) -> Result(
      request.Request(List(#(String, String))),
      RequestError,
    ),
  )
}

Constructors

AuthorizationSetter(
  setter: fn(request.Request(List(#(String, String)))) -> Result(
    request.Request(List(#(String, String))),
    RequestError,
  ),
)

ClientAuthentication

</>

The type of client authentication that should be used with the OAuth 2.0 Server. An OAuth 2.0 Server can support multiple kinds of client authentication. When the incorrect kind is used, the OAuth 2.0 Server will respond with an error. For the error information see RFC6749 Error Response.

pub type ClientAuthentication {
  ClientSecretBasic(client_id: ClientId, client_secret: Secret)
  ClientSecretPost(client_id: ClientId, client_secret: Secret)
  PublicAuthentication(client_id: ClientId)
}

Constructors

```
ClientSecretBasic(client_id: ClientId, client_secret: Secret)
```
Use this type if the OAuth 2.0 Server accepts HTTP Basic authentication, which sets the Authorization header in the HTTP request. For example:
```
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
```
```
ClientSecretPost(client_id: ClientId, client_secret: Secret)
```
Use this type if the OAuth 2.0 Server accepts the credentials via a POST request. In that case the credentials are sent URL encoded. For example:
```
client_id=asdf&client_secret=hjkl
```
```
PublicAuthentication(client_id: ClientId)
```
Use this type if the client is public and there is not client secret to be included.

ClientId

</>

Type to indicate the client ID. Mostly used to have type-safe parameters, so client id, client secret, etc are not mixed up. See RFC6749

pub type ClientId {
  ClientId(value: String)
}

Constructors

```
ClientId(value: String)
```

RequestError

</>

Errors returned by this module when creating requests

pub type RequestError {
  SecretExpired
  InvalidUri
}

Constructors

```
SecretExpired
```
Will be returned if an expired secret is used.
```
InvalidUri
```
Will be returned if an invalid URL is provided

ResponseError

</>

Errors returned by this module when parsing responses, such as token responses from the OAuth 2.0 server.

pub type ResponseError {
  ErrorResponse(
    status: Int,
    error: String,
    error_description: option.Option(String),
    error_uri: option.Option(String),
  )
  ParseError(error: json.DecodeError)
}

Constructors

```
ErrorResponse(
  status: Int,
  error: String,
  error_description: option.Option(String),
  error_uri: option.Option(String),
)
```
If the response contains errors a ErrorResponse will be returned. It contains the HTTP status, the error code string, optionally an error description and an error URI.
```
ParseError(error: json.DecodeError)
```
If the response does not contain valid JSON or does not conform to the error response format defined by RFC6749 Error Response this error will be returned.

Scope

</>

Type alias for the scope. A scope is a list of strings. See RFC6749

pub type Scope =
  List(String)

Secret

</>

Type to indicate the client secret. Mostly used to have type-safe parameters, so client id, client secret, etc are not mixed up. See RFC6749

pub type Secret {
  Secret(value: String)
  SecretWithExpiration(
    value: String,
    expires_at: timestamp.Timestamp,
  )
}

Constructors

```
Secret(value: String)
```
A normal OAuth 2.0 client secret
```
SecretWithExpiration(
  value: String,
  expires_at: timestamp.Timestamp,
)
```
A client secret with an expiration date attached. Can be used to check if the secret expired.

TokenRequest

</>

The essential requests of OAuth 2.0. The token requests includes all the different Grant Types defined in RFC6749.

pub type TokenRequest {
  AuthorizationCodeGrantTokenRequest(
    token_endpoint: uri.Uri,
    authentication: ClientAuthentication,
    redirect_uri: option.Option(uri.Uri),
    code: String,
  )
  AuthorizationCodeGrantTokenRequestWithPKCE(
    token_endpoint: uri.Uri,
    authentication: ClientAuthentication,
    redirect_uri: option.Option(uri.Uri),
    code: String,
    code_verifier: String,
  )
  ResourceOwnerCredentialsGrantTokenRequest(
    token_endpoint: uri.Uri,
    authentication: ClientAuthentication,
    username: String,
    password: String,
    scope: List(String),
  )
  RefreshTokenGrantRequest(
    token_endpoint: uri.Uri,
    authentication: ClientAuthentication,
    refresh_token: String,
    scope: List(String),
  )
  ClientCredentialsGrantTokenRequest(
    token_endpoint: uri.Uri,
    authentication: ClientAuthentication,
    scope: List(String),
  )
}

Constructors

AuthorizationCodeGrantTokenRequest(
  token_endpoint: uri.Uri,
  authentication: ClientAuthentication,
  redirect_uri: option.Option(uri.Uri),
  code: String,
)

A token request for the Authorization Code Grant Type. Use the AuthorizationCodeGrantRedirectUri to retrieve the code. See RFC6749 Authorization Code Grant.

AuthorizationCodeGrantTokenRequestWithPKCE(
  token_endpoint: uri.Uri,
  authentication: ClientAuthentication,
  redirect_uri: option.Option(uri.Uri),
  code: String,
  code_verifier: String,
)

A token request for the Authorization Code Grant Type with a PKCE code verifier. Use the AuthorizationCodeGrantRedirectUri to retrieve the code. See RFC6749 Authorization Code Grant and RFC7636.

ResourceOwnerCredentialsGrantTokenRequest(
  token_endpoint: uri.Uri,
  authentication: ClientAuthentication,
  username: String,
  password: String,
  scope: List(String),
)

A token request for the Resource Owner Password Grant Type. See RFC6749 Resource Owner Password Grant.

```
RefreshTokenGrantRequest(
  token_endpoint: uri.Uri,
  authentication: ClientAuthentication,
  refresh_token: String,
  scope: List(String),
)
```
This token request is used to refresh an expired access token. After a successful token request, the OAuth 2.0 Server can respond with an access token and/or a refresh token. The refresh token can be used to get a new access token. See RFC6749 Refreshing an Access Token.

ClientCredentialsGrantTokenRequest(
  token_endpoint: uri.Uri,
  authentication: ClientAuthentication,
  scope: List(String),
)

This token request is used to retrieve an access token using the client id and client secret. See RFC6749 Client Credentials Grant.

UrlEncRequest

</>

Type alias for URL encoded http requests.

pub type UrlEncRequest =
  request.Request(List(#(String, String)))

Values

add_scope

</>

pub fn add_scope(
  d: List(#(String, String)),
  scope: List(String),
) -> List(#(String, String))

Function that adds a scope to a list if the scope is not empty.

authorization_setter

</>

pub fn authorization_setter(
  auth: ClientAuthentication,
) -> AuthorizationSetter

Encodes the ClientAuthentication that is to be sent to the OAuth 2.0 Server. For Basic Authentication it will always encode it with base64.

is_secret_invalid

</>

pub fn is_secret_invalid(secret: Secret) -> Bool

Checks if a given secret is expired. Returns always false for secrets that cannot expire.

parse_error_response

</>

pub fn parse_error_response(
  response: response.Response(String),
) -> ResponseError

Parses an OAuth 2.0 error response defined in RFC6749 Error Response.

parse_scope

</>

pub fn parse_scope(scope: String) -> List(String)

Parses a string containing the space separated scopes.

Example

parse_scope("scope1 scope2")

parse_token_response

</>

pub fn parse_token_response(
  response: response.Response(String),
) -> Result(AccessTokenResponse, ResponseError)

Parses a token response and returns the access and refresh token if valid response, otherwise the error response.

secret_is_valid

</>

pub fn secret_is_valid(secret: Secret) -> Bool

Checks if a given secret is not expired. Returns always true for secrets that cannot expire.

setup_request

</>

pub fn setup_request(
  endpoint endpoint: uri.Uri,
  body body: List(#(String, String)),
  client_auth client_auth: AuthorizationSetter,
) -> Result(request.Request(String), RequestError)

A helper function that maps a general request with credentials to a gleam http request. The credentials are either attached to the request body URL encoded or added as basic authorization header.

to_http_request

</>

pub fn to_http_request(
  request: TokenRequest,
) -> Result(request.Request(String), RequestError)

Creates a http request from the given TokenRequest, but does not send. Sending the request is done by the user of the function.

to_string_token_response

</>

pub fn to_string_token_response(
  resp: AccessTokenResponse,
) -> String

Creates a String representation of a token request