gloak/oidc

Sans-IO OpenID Connect and OAuth2 helpers for Keycloak.

This module builds gleam_http requests for discovery, authorization, token, userinfo, introspection, revocation, logout, and JWKS endpoints. It decodes responses into small stable records. It does not send requests, persist sessions, generate entropy, or verify JWT signatures; use a JOSE library such as gose for signature and claim verification.

Examples

import gloak
import gloak/oidc

pub fn discovery(server, realm) {
  oidc.discovery_request(server, realm)
}

Types

Introspection

@superdocs OIDC Models OAuth2 token introspection response.

pub type Introspection {
  Introspection(
    activity: gloak.TokenActivity,
    subject: option.Option(String),
    username: option.Option(String),
    client_id: option.Option(String),
    scope: option.Option(String),
  )
}

Constructors

Introspection(
  activity: gloak.TokenActivity,
  subject: option.Option(String),
  username: option.Option(String),
  client_id: option.Option(String),
  scope: option.Option(String),
)

JsonWebKey

@superdocs OIDC Models Minimal JSON Web Key representation from a JWKS response.

pub type JsonWebKey {
  JsonWebKey(
    kid: String,
    kty: String,
    alg: option.Option(String),
    use_: option.Option(String),
    n: option.Option(String),
    e: option.Option(String),
  )
}

Constructors

JsonWebKey(
  kid: String,
  kty: String,
  alg: option.Option(String),
  use_: option.Option(String),
  n: option.Option(String),
  e: option.Option(String),
)

Metadata

@superdocs OIDC Models Discovered OpenID Provider metadata used by OIDC request builders.

pub type Metadata {
  Metadata(
    issuer: String,
    authorization_endpoint: String,
    token_endpoint: String,
    userinfo_endpoint: String,
    jwks_uri: String,
    introspection_endpoint: String,
    revocation_endpoint: String,
    end_session_endpoint: String,
    id_token_signing_alg_values_supported: List(String),
  )
}

Constructors

Metadata(
  issuer: String,
  authorization_endpoint: String,
  token_endpoint: String,
  userinfo_endpoint: String,
  jwks_uri: String,
  introspection_endpoint: String,
  revocation_endpoint: String,
  end_session_endpoint: String,
  id_token_signing_alg_values_supported: List(String),
)

TokenResponse

@superdocs OIDC Models OAuth token response returned by token endpoint flows.

pub type TokenResponse {
  TokenResponse(
    access_token: gloak.AccessToken,
    refresh_token: option.Option(gloak.RefreshToken),
    id_token: option.Option(gloak.IdToken),
    expires_in: Int,
    token_type: String,
    scope: option.Option(String),
  )
}

Constructors

TokenResponse(
  access_token: gloak.AccessToken,
  refresh_token: option.Option(gloak.RefreshToken),
  id_token: option.Option(gloak.IdToken),
  expires_in: Int,
  token_type: String,
  scope: option.Option(String),
)

UserInfo

@superdocs OIDC Models UserInfo claims commonly returned by Keycloak.

pub type UserInfo {
  UserInfo(
    subject: String,
    preferred_username: option.Option(String),
    email: option.Option(String),
    email_verification: option.Option(gloak.EmailVerification),
    name: option.Option(String),
  )
}

Constructors

UserInfo(
  subject: String,
  preferred_username: option.Option(String),
  email: option.Option(String),
  email_verification: option.Option(gloak.EmailVerification),
  name: option.Option(String),
)

Values

authorization_code_token_request

pub fn authorization_code_token_request(
  metadata: Metadata,
  client_id: gloak.ClientId,
  client_secret: option.Option(gloak.ClientSecret),
  code: String,
  redirect_uri: String,
  code_verifier: String,
) -> Result(request.Request(String), gloak.Error)

@superdocs Tokens Builds an Authorization Code token request.

authorization_request

pub fn authorization_request(
  metadata: Metadata,
  client_id: gloak.ClientId,
  redirect_uri: String,
  scopes: List(String),
  state: String,
  nonce: option.Option(String),
  code_challenge: option.Option(String),
  extra_query: List(#(String, String)),
) -> Result(request.Request(String), gloak.Error)

@superdocs Authorization Builds a browser authorization redirect request.

callback_response

pub fn callback_response(
  callback_url: String,
  expected_state: String,
) -> Result(String, gloak.Error)

@superdocs Authorization Parses an authorization callback URL and validates the returned state.

client_credentials_request

pub fn client_credentials_request(
  metadata: Metadata,
  client_id: gloak.ClientId,
  client_secret: gloak.ClientSecret,
  scopes: List(String),
) -> Result(request.Request(String), gloak.Error)

@superdocs Tokens Builds a Client Credentials token request.

discovery_request

pub fn discovery_request(
  server: gloak.Server,
  realm: gloak.Realm,
) -> request.Request(String)

@superdocs Discovery Builds the OpenID Provider Configuration discovery request.

discovery_response

pub fn discovery_response(
  response: response.Response(String),
  expected_issuer: String,
) -> Result(Metadata, gloak.Error)

@superdocs Discovery Decodes OpenID Provider metadata and validates its issuer.

introspection_request

pub fn introspection_request(
  metadata: Metadata,
  client_id: gloak.ClientId,
  client_secret: gloak.ClientSecret,
  token: gloak.AccessToken,
) -> Result(request.Request(String), gloak.Error)

@superdocs Introspection Builds a token introspection request.

introspection_response

pub fn introspection_response(
  response: response.Response(String),
) -> Result(Introspection, gloak.Error)

@superdocs Introspection Decodes a token introspection response.

jwks_request

pub fn jwks_request(
  metadata: Metadata,
) -> Result(request.Request(String), gloak.Error)

@superdocs JWKS Builds a JWKS fetch request.

jwks_response

pub fn jwks_response(
  response: response.Response(String),
) -> Result(List(JsonWebKey), gloak.Error)

@superdocs JWKS Decodes a JWKS response into raw public keys for a JOSE verifier.

logout_request

pub fn logout_request(
  metadata: Metadata,
  client_id: gloak.ClientId,
  id_token_hint: option.Option(gloak.IdToken),
  post_logout_redirect_uri: option.Option(String),
  state: option.Option(String),
) -> Result(request.Request(String), gloak.Error)

@superdocs Logout Builds an RP-initiated logout request.

pkce_s256_challenge

pub fn pkce_s256_challenge(
  verifier: String,
) -> Result(String, gloak.Error)

@superdocs Authorization Builds the RFC7636 S256 PKCE challenge for a caller-provided verifier.

The verifier must come from caller-managed entropy. This helper only hashes and base64url-encodes it so the library remains Sans-IO.

refresh_token_request

pub fn refresh_token_request(
  metadata: Metadata,
  client_id: gloak.ClientId,
  client_secret: option.Option(gloak.ClientSecret),
  refresh_token: gloak.RefreshToken,
) -> Result(request.Request(String), gloak.Error)

@superdocs Tokens Builds a Refresh Token request.

revocation_request

pub fn revocation_request(
  metadata: Metadata,
  client_id: gloak.ClientId,
  client_secret: option.Option(gloak.ClientSecret),
  token: String,
) -> Result(request.Request(String), gloak.Error)

@superdocs Revocation Builds a token revocation request.

revocation_response

pub fn revocation_response(
  response: response.Response(String),
) -> Result(Nil, gloak.Error)

@superdocs Revocation Decodes a revocation response whose success body is ignored.

token_response

pub fn token_response(
  response: response.Response(String),
) -> Result(TokenResponse, gloak.Error)

@superdocs Tokens Decodes token endpoint responses.

userinfo_request

pub fn userinfo_request(
  metadata: Metadata,
  access_token: gloak.AccessToken,
) -> Result(request.Request(String), gloak.Error)

@superdocs UserInfo Builds a UserInfo request.

userinfo_response

pub fn userinfo_response(
  response: response.Response(String),
) -> Result(UserInfo, gloak.Error)

@superdocs UserInfo Decodes a UserInfo response.