forked from Telodendria/Telodendria
Document Uia API.
This commit is contained in:
parent
17734c90e8
commit
04bf8ca1a1
4 changed files with 128 additions and 5 deletions
4
TODO.txt
4
TODO.txt
|
@ -22,11 +22,11 @@ Milestone: v0.2.0
|
|||
[x] User login
|
||||
[x] Logout all
|
||||
|
||||
[~] Documentation
|
||||
[x] Documentation
|
||||
[x] User functions
|
||||
[x] Json functions
|
||||
[x] Db functions
|
||||
[ ] Uia (move docs from Matrix)
|
||||
[x] Uia (move docs from Matrix)
|
||||
|
||||
[x] Convert proposals to man pages
|
||||
|
||||
|
|
123
man/man3/Uia.3
Normal file
123
man/man3/Uia.3
Normal file
|
@ -0,0 +1,123 @@
|
|||
.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
|
|
@ -181,13 +181,13 @@ UiaDummyFlow(void)
|
|||
return NULL;
|
||||
}
|
||||
|
||||
ArrayAdd(response, UiaBuildStage("m.login.dummy", NULL));
|
||||
ArrayAdd(response, UiaStageBuild("m.login.dummy", NULL));
|
||||
|
||||
return response;
|
||||
}
|
||||
|
||||
UiaStage *
|
||||
UiaBuildStage(char *type, HashMap * params)
|
||||
UiaStageBuild(char *type, HashMap * params)
|
||||
{
|
||||
UiaStage *stage = Malloc(sizeof(UiaStage));
|
||||
|
||||
|
|
|
@ -32,7 +32,7 @@
|
|||
typedef struct UiaStage UiaStage;
|
||||
|
||||
extern UiaStage *
|
||||
UiaBuildStage(char *, HashMap *);
|
||||
UiaStageBuild(char *, HashMap *);
|
||||
|
||||
extern Array *
|
||||
UiaDummyFlow(void);
|
||||
|
|
Loading…
Reference in a new issue