Iddawc
Handle the flow of OAuth2 and OpenID Connect authentication process from the client side.
|
Iddawc is a C library used to implement OAuth2/OIDC clients according to the OAuth2 RFC and the OpenID Connect Specs.
It's based on Ulfius library for the HTTP requests and response management and Rhonabwy library for the JWKs management.
Iddawc supports the following features:
auth
requests using the given parameters (client_id
, client_secret
, redirect_uri
, etc.) and parsing the resulttoken
requests using the given parameters (code
, client_id
, client_secret
, redirect_uri
, etc.) and parsing the resultuserinfo
, token introspection
, token revocation
requestsregister
endpoint if anyauth
and token
endpointsLots of functions in Rhonabwy library return an int value. The returned value can be one of the following:
If a function is succesfull, it will return I_OK
(0), otherwise an error code is returned.
Usually, a log message is displayed to explain more specifically what happened on error. The log manager used is Yder. You can enable yder log messages on the console with the following command at the beginning of your program:
Example of an error log message:
Go to Yder API Documentation for more details.
Iddawc is based in the struct _i_session
to store all the required parameters and results to work. You must use the init and clean functions before using a struct _i_session *
and after finishing using it.
To set or get parameters stored in the struct _i_session *
, you must use the appropriate function
Iddawc supports importing or exporting struct _i_session *
. The export format is JSON
. Be careful, the JSON output is unsecured and contains all secrets and tokens without encryption!
You can import and export either in json_t *
or char *
, the char *
format is a JSON stringified.
Finally, to run OAuth2 or OIDC requests, you must use the dedicated functions using the initialized and set struct _i_session *
and some additional parameters if required.
When available, you can load the Openid Config endpoint. This will parse the result and fill the struct _i_session *
parameters with all the required results (auth endpoint, public keys, signature algorithms, etc.). Using this function required to have set the property I_OPT_OPENID_CONFIG_ENDPOINT
.
The function i_build_auth_url_get
can be used to build the full auth request with all the parameters in the url query for a GET request.
The function i_run_auth_request
builds the full auth requests and executes it. If the OAuth2 server answers with a succesfull response, the response will be parsed in the session properties. Otherwise, the rediect_to value and the errors if any will be parsed and made available in the session properties.
If the auth request is executed by an external program such as the browser, you can parse the redirect_to response afterwards using this function. You must set the I_OPT_REDIRECT_TO
.
If you need to execute a request in the token endpoint, to get a refresh token from a code or refresh a token for example,
If the auth or token endpoints returns an id_token, this one will be parsed, the signature will be verified and the content will be validated to make sure the id_token is valid. You can also manually validate an id_token using the dedicated function. The property I_OPT_ID_TOKEN
and the publick key property must be set.
If an access_token is available, you can make a request to the userinfo endpoint to get information about the user. The function i_load_userinfo_custom
is a more advanced userinfo request where you can specify query or header parameters, to request more claims or the result a signed JWT.
To execute introspection or revocation requests, you must set the session property I_OPT_TOKEN_TARGET
and I_OPT_TOKEN_TARGET_TYPE_HINT
if required.
If available, you can register a new client. You may have to set a I_OPT_ACCESS_TOKEN
property, depending on the server configuration. If update_session
is true and the registration is successfull, the properties I_OPT_CLIENT_ID
and I_OPT_CLIENT_SECRET
will be set to the session, and the first redirect_to
entry will be used as I_OPT_REDIRECT_TO
value.