Skip to content

Latest commit

 

History

History
131 lines (100 loc) · 3.98 KB

README.md

File metadata and controls

131 lines (100 loc) · 3.98 KB
Raw

Shin

🍀 A collection of lightweight auth utilities for Elixir.

Introduction

Shin 信 means "trust", "faith", or "belief" in Japanese.

This package aims to provide lightweight utilities that can be used to ensure that primitives are well validated and trusted for usage by auth providers.

Playground

A UI playground with usage example per utility can be found at https://shin.howauth.com

Getting started

The package can be installed by adding shin_auth to your list of dependencies in mix.exs:

def deps do
  [
    {:shin_auth, "~> 1.3.0"}
  ]
end

Utilities per protocol

OpenID Connect (OIDC)

load_provider_configuration

Based on the spec: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata

Loads, validates and parses the Identity Provider configuration based on their discovery endpoint metadata.

With valid configuration, returns parsed metadata:

iex(1)> ShinAuth.OIDC.load_provider_configuration("https://valid-url/.well-known/openid-configuration")
{:ok, %ShinAuth.OIDC.ProviderConfiguration.Metadata{}}

With invalid configuration, returns error:

iex(1)> ShinAuth.OIDC.load_provider_configuration("https://invalid-discovery/.well-known/openid-configuration")
{:error, %ShinAuth.OIDC.ProviderConfiguration.Error{}}

Here's a list of error per tags:

Tags Reason
malformed_discovery_endpoint or discovery_endpoint_unreachable The provided endpoint is either malformed or unreachable via HTTP request
authorization_endpoint_unreachable authorization_code is unreachable via HTTP request
token_endpoint_unreachable token_endpoint is unreachable via HTTP request
jwks_uri_unreachable or malformed_jwks_uri_response jwks_uri is either unreachable via HTTP request or the response is malformed
missing_issuer_attribute issuer attribute is missing from the provider's metadata

Security Assertion Markup Language (SAML)

decode_saml_response

Parsed a given SAML response to a struct with attributes and values:

iex(1)> ShinAuth.SAML.decode_saml_response(saml_response_xml)

{:ok, %ShinAuth.SAML.Response{
   common: %ShinAuth.SAML.Response.Common{
     id: "_123",
     version: "2.0",
     destination: "https://api.example.com/sso/saml/acs/123",
     issuer: "https://example.com/1234/issuer/1234",
     issue_instant: "2024-03-23T20:56:56.768Z"
   },
   status: %ShinAuth.SAML.Response.Status{
     status: :success,
     status_code: "urn:oasis:names:tc:SAML:2.0:status:Success"
   },
   conditions: %ShinAuth.SAML.Response.Conditions{
     not_before: "2024-03-23T20:56:56.768Z",
     not_on_or_after: "2024-03-23T21:01:56.768Z"
   },
   attributes: [
     %ShinAuth.SAML.Response.Attribute{
       name: "id",
       value: "209bac63df9962e7ec458951607ae2e8ed00445a"
     },
     %ShinAuth.SAML.Response.Attribute{
       name: "email",
       value: "foo@corp.com"
     },
     %ShinAuth.SAML.Response.Attribute{
       name: "firstName",
       value: "Laura"
     },
     %ShinAuth.SAML.Response.Attribute{
       name: "lastName",
       value: "Beatris"
     },
     %ShinAuth.SAML.Response.Attribute{name: "groups", value: ""}
   ]
 }}

decode_saml_request

Parsed a given SAML request to a struct with attributes and values:

iex(1)> ShinAuth.SAML.decode_saml_request(saml_request_xml)

{:ok, %ShinAuth.SAML.Request{
   common: %ShinAuth.SAML.Request.Common{
     id: "_123",
     version: "2.0",
     assertion_consumer_service_url: "https://auth.example.com/sso/saml/acs/123",
     issuer: "https://example.com/123",
     issue_instant: "2023-09-27T17:20:42.746Z"
   }
 }}