# `ExSaml`
[🔗](https://github.com/docJerem/ex_saml/blob/main/lib/ex_saml.ex#L1)

SAML 2.0 Service Provider (SP) library for Elixir/Phoenix applications.

Provides functions to retrieve active SAML assertions and their attributes
from the current Plug session.

# `get_acs_uri`

Returns the Assertion Consumer Service (ACS) URI for the given IdP.

# `get_active_assertion`

```elixir
@spec get_active_assertion(Plug.Conn.t()) :: nil | ExSaml.Assertion.t()
```

Returns authenticated user SAML Assertion.

The struct includes the attributes sent from IdP as well as any corresponding locally
computed/derived attributes. Returns `nil` if the current Plug session
is not authenticated.

## Parameters

+   `conn` - Plug connection

## Examples

    # When there is an authenticated SAML assertion
    %Assertion{} = ExSaml.get_active_assertion(conn)

# `get_attribute`

```elixir
@spec get_attribute(nil | ExSaml.Assertion.t(), ExSaml.Assertion.attr_name_t()) ::
  nil | ExSaml.Assertion.attr_value_t()
```

Returns value of the specified attribute name in the given SAML Assertion.

Checks for the attribute in `computed` map first and `attributes` map next.
Returns a UTF-8 binary or a list of UTF-8 binaries (in case of multi-valued)
if the given attribute is present. Returns `nil` if attribute is not present.

## Parameters

+   `assertion` - SAML assertion obtained by calling `get_active_assertion/1`
+   `name`: Attribute name

## Examples

    assertion = ExSaml.get_active_assertion(conn)
    # returns a list if the attribute is multi-valued
    roles = ExSaml.get_attribute(assertion, "roles")
    computed_fullname = ExSaml.get_attribute(assertion, "fullname")

# `get_metadata_uri`

Returns the SP metadata URI for the given IdP.

# `get_signin_uri`

Returns the sign-in URI for the given IdP.

# `get_slo_response_uri`

Returns the SLO response URI for the given IdP.

# `get_slo_uri`

Returns the Single Logout (SLO) URI for the given IdP.

# `list_identity_providers`

Lists identity providers from the configured accessor function.

Requires `identity_providers_accessor` to be set in config:

    config :ex_saml,
      identity_providers_accessor: &MyApp.Saml.identity_providers/0

# `list_service_providers`

Lists service providers from the configured accessor function.

Requires `service_providers_accessor` to be set in config:

    config :ex_saml,
      service_providers_accessor: &MyApp.Saml.service_providers/0

---

*Consult [api-reference.md](api-reference.md) for complete listing*