% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(saml): SAML Authentication}

\label{sec:saml}

\begin{tags}
    \tag{See also}
\url{https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf}

There are four primary integration points for applications to use this code:
1) You must declare at least one service provider (SP)
2) You must declare at least one identity provider (IdP) per SP
3) Finally, you can call \verb$saml_authenticate(+SP, +IdP, +Callback, +Request)$ to obtain assertions
The asynchronous nature of the SAML process means that a callback must be used. Assuming
that the IdP was able to provide at least some valid assertions about the user, after calling
Callback with 2 extra arguments (a list of the assertion terms and the URL being request by
the user), the user will be redirected back to their original URL. It is therefore up to the
callback to ensure that this does not simply trigger another round of SAML negotiations - for
example, by throwing \verb$http_reply(forbidden(RequestURL))$ if the assertions are not strong enough
4) Finally, your SP metadata will be available from the web server directly. This is required to
configure the IdP. This will be available at './metadata.xml', relative to the LocationSpec
provided when the SP was declared.

\begin{center}
Configuring an SP:
To declare an SP, use the declaration
\Sneck{}\verb$saml_sp(+ServiceProvider: atom, +LocationSpec: term, +PrivateKeySpec: term, +Password: atom +CertificateSpec: term, +Options: list)$.
\end{center}

The ServiceProvider is the identifier of your service. Ideally, this should be a fully-qualified URI
The LocationSpec is a location that the HTTP dispatch layer will understand
for example '.' or \verb$root('saml')$.
The Private KeySpec is a 'file specifier' that resolves to a private key (see below for specifiers)
The Password is a password used for reading the private key. If the key is not encrypted, any atom
can be supplied as it will be ignored
The CertificateSpec is a file specifier that resolves to a certificate holding the public key
corresponding to PrivateKeySPec
There are currently no implemented options (the list is ignored).

\begin{center}
Configuring an IdP:
To declare an IdP, use the declaration
\Sneck{}\verb$saml_idp(+ServiceProvider: atom, +MetadataSpec: term)$.
ServiceProvider is the identifier used when declaring your SP. You do not need to declare them in a
particular order, but both must be present in the system before running \predref{saml_authenticate}{4}.
MetadataSpec is a file specifier that resolves to the metadata for the IdP. Most IdPs will be able
to provide this on request
\end{center}

File Specifiers:
The following specifiers are supported for locating files:

\begin{itemize}
    \item \verb$file(Filename)$: The local file Filename
    \item \verb$resource(Resource)$: The prolog resource Resource. See \predref{resource}{3}
    \item \verb$url(URL)$: The file identified by the HTTP (or HTTPS if you have the HTTPS plugin loaded) URL
\end{itemize}
\end{tags}

This library uses SAML to exchange messages with an Identity Provider to establish
assertions about the current user's session. It operates only as the service end, not
the identity provider end.\vspace{0.7cm}