forked from Telodendria/Telodendria
124 lines
4.5 KiB
Groff
124 lines
4.5 KiB
Groff
.Dd $Mdocdate: March 7 2023 $
|
|
.Dt UIA 3
|
|
.Os Telodendria Project
|
|
.Sh NAME
|
|
.Nm Uia
|
|
.Nd User Interactive Authentication API.
|
|
.Sh SYNOPSIS
|
|
.In Uia.h
|
|
.Ft UiaStage *
|
|
.Fn UiaStageBuild "char *" "HashMap *"
|
|
.Ft Array *
|
|
.Fn UiaDummyFlow "void"
|
|
.Ft void
|
|
.Fn UiaCleanup "MatrixHttpHandlerArgs *"
|
|
.Ft int
|
|
.Fn UiaComplete "Array *" "HttpServerContext *" "Db *" "HashMap *" "HashMap **" "TelodendriaConfig *"
|
|
.Ft void
|
|
.Fn UiaFlowsFree "Array *"
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
takes care of all the logic for performing user interactive
|
|
authentication as defined by the Matrix specification. API endpoints
|
|
that require authentication via user interactive authentication
|
|
build up flows and any necessary parameters, and pass them into
|
|
.Fn UiaComplete ,
|
|
which validates
|
|
.Dv auth
|
|
objects and maintains session state to track the progress of a
|
|
client through the user interactive authentication flows. The idea
|
|
is that an API endpoint will not progress until user interactive
|
|
authentication has succeeded.
|
|
.Nm
|
|
makes it easy for the numerous API endpoints that utilize this
|
|
authentication mechanism to implement it.
|
|
.Pp
|
|
.Fn UiaStageBuild
|
|
builds a single stage. A stage consists of a string identifying its
|
|
type, which is used to instruct the client as to what should be
|
|
done, and parameters, which is a JSON object that contains
|
|
implementation-specific parameters for completing the stage. This
|
|
function takes those two parameters in that order.
|
|
.Pp
|
|
.Fn UiaDummyFlow
|
|
builds a flow that consists only of a dummy stage. This is useful
|
|
when an endpoint is required to use user interactive authentication,
|
|
but doesn't actually want to require the user to do anything. Since
|
|
the dummy flow is a pretty common flow, it seemed sensible to have
|
|
a function for it. Other flows are built by the caller that wishes
|
|
to perform user interactive authentication.
|
|
.Pp
|
|
.Fn UiaCleanup
|
|
should be called periodically to purge old sessions. Session are
|
|
only valid for a few minutes after their last access. After that, they
|
|
should be purged so the database doesn't fill up with session files.
|
|
This function is specifically designed to be called via
|
|
.Xr Cron 3 .
|
|
.Pp
|
|
.Fn UiaComplete
|
|
does the bulk of the work for user interactive authentication. It
|
|
takes many paramters:
|
|
.Bl -bullet
|
|
.It
|
|
An array of arrays of stages. Stages should be created with
|
|
.Fn UiaStageBuild ,
|
|
and then put into an array to create a flow. Those flows should then
|
|
be put into an array and passed as this paramter. Do note that
|
|
because of the loose typing of Telodendria's Array API, it is very
|
|
easy to make mistakes here; if you are implementing a new route that
|
|
requires user interactive authentication, then refer to an existing
|
|
route so you can see how it works.
|
|
.It
|
|
An HTTP server context. This is required to set the response headers
|
|
in the event of an error.
|
|
.It
|
|
The database where user interactive authentication sessons are
|
|
persisted.
|
|
.It
|
|
The JSON request body that contains the client's
|
|
.Dv auth
|
|
object, which will be read, parsed, and handled as appropriate.
|
|
.It
|
|
A pointer to a pointer where a JSON response can be placed if
|
|
necessary. If
|
|
.Fn UiaComplete
|
|
encounters a client error, such as a failure to authenticate, or
|
|
outstanding stages that have not been completed, it will place a
|
|
JSON response here that is expected to be returned to the client.
|
|
This response will include a description of all the flows, stages,
|
|
and their parameters.
|
|
.It
|
|
A valid Telodendria configuration structure, because a few values
|
|
are read from the configuration during certain stages of the
|
|
authentication.
|
|
.El
|
|
.Pp
|
|
.Fn UiaFlowsFree
|
|
frees an array of flows, as described above. Even though the
|
|
caller constructs this array, it is convenient to free it in its
|
|
entirety in a single function call.
|
|
.Sh RETURN VALUES
|
|
.Pp
|
|
.Fn UiaStageBuild
|
|
returns an opaque structure that represents a user interactive
|
|
authentication stage, and any parameters the client needs to complete
|
|
it. It may return NULL if there is an error allocating memory.
|
|
.Pp
|
|
.Fn UiaDummyFlow
|
|
returns an array that represents a dummy authentication flow, or
|
|
NULL if it could not allocate memory for it.
|
|
.Pp
|
|
.Fn UiaComplete
|
|
returns an integer less than zero if it experiences an internal
|
|
failure, such as a failure to allocate memory, or a corrupted
|
|
database. It returns 0 if the client has remaining stages to
|
|
complete. In this case, it will have set the response headers
|
|
and the passed response pointer, so the caller should immediately
|
|
return the response to the client. This function returns 1 if the
|
|
user has successfully completed all stages. Only in this case shall
|
|
the caller proceed with its logic.
|
|
.Sh SEE ALSO
|
|
.Xr User 3 ,
|
|
.Xr Db 3 ,
|
|
.Xr Cron 3
|