Iddawc
Handle the flow of OAuth2 and OpenID Connect authentication process from the client side.
Iddawc API documentation

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:

  • Loading openid-configuration endpoints and parsing the results
  • Making auth requests using the given parameters (client_id, client_secret, redirect_uri, etc.) and parsing the result
  • Making token requests using the given parameters (code, client_id, client_secret, redirect_uri, etc.) and parsing the result
  • Making userinfo, token introspection, token revocation requests
  • Parse responses, validate id_token
  • Registering new clients using the register endpoint if any
  • Sending signed and or encrypted requests in the auth and token endpoints

Return values

Lots of functions in Rhonabwy library return an int value. The returned value can be one of the following:

#define I_OK 0
#define I_ERROR 1
#define I_ERROR_PARAM 2
#define I_ERROR_MEMORY 3
#define I_ERROR_UNAUTHORIZED 4
#define I_ERROR_SERVER 5

If a function is succesfull, it will return I_OK (0), otherwise an error code is returned.

Log messages

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:

int main() {
y_init_logs("Iddawc", Y_LOG_MODE_CONSOLE, Y_LOG_LEVEL_DEBUG, NULL, "Starting Iddawc client program");
// Do your code here
y_close_logs();
}

Example of an error log message:

2020-04-05T16:14:31 - Iddawc: i_run_auth_request - Unsupported auth_method

Go to Yder API Documentation for more details.

Core functions and struct _i_session * variables

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.

int i_init_session(struct _i_session * i_session);
void i_clean_session(struct _i_session * i_session);

Get or set properties

To set or get parameters stored in the struct _i_session *, you must use the appropriate function

int i_set_response_type(struct _i_session * i_session, uint i_value);
int i_set_result(struct _i_session * i_session, uint i_value);
int i_set_int_parameter(struct _i_session * i_session, i_option option, uint i_value);
int i_set_str_parameter(struct _i_session * i_session, i_option option, const char * s_value);
int i_set_additional_parameter(struct _i_session * i_session, const char * s_key, const char * s_value);
int i_set_additional_response(struct _i_session * i_session, const char * s_key, const char * s_value);
uint i_get_response_type(struct _i_session * i_session);
uint i_get_result(struct _i_session * i_session);
uint i_get_int_parameter(struct _i_session * i_session, i_option option);
const char * i_get_str_parameter(struct _i_session * i_session, i_option option);
const char * i_get_additional_parameter(struct _i_session * i_session, const char * s_key);
const char * i_get_additional_response(struct _i_session * i_session, const char * s_key);

Import or export sessions

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.

json_t * i_export_session_json_t(struct _i_session * i_session);
int i_import_session_json_t(struct _i_session * i_session, json_t * j_import);
char * i_export_session_str(struct _i_session * i_session);
int i_import_session_str(struct _i_session * i_session, const char * str_import);

Run OAuth2 or OIDC requests

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.

Load openid-config

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.

int i_load_openid_config(struct _i_session * i_session);

Build and run auth request and parse results

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.

int i_build_auth_url_get(struct _i_session * i_session);

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.

int i_run_auth_request(struct _i_session * i_session);

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.

int i_parse_redirect_to(struct _i_session * i_session);

Build and run token requests and parse results

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,

int i_run_token_request(struct _i_session * i_session);

Verify an id_token

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.

int i_verify_id_token(struct _i_session * i_session);

Load userinfo

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.

int i_load_userinfo(struct _i_session * i_session);
int i_load_userinfo_custom(struct _i_session * i_session, const char * http_method, struct _u_map * additional_query, struct _u_map * additional_headers);

Introspect or revoke tokens

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.

int i_introspect_token(struct _i_session * i_session, json_t ** j_result);
int i_revoke_token(struct _i_session * i_session);

Register new clients

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.

int i_register_client(struct _i_session * i_session, json_t * j_parameters, int update_session, json_t ** j_result);
i_load_userinfo
int i_load_userinfo(struct _i_session *i_session)
Definition: iddawc.c:1535
i_import_session_json_t
int i_import_session_json_t(struct _i_session *i_session, json_t *j_import)
Definition: iddawc.c:2691
i_get_result
uint i_get_result(struct _i_session *i_session)
Definition: iddawc.c:1667
i_parse_redirect_to
int i_parse_redirect_to(struct _i_session *i_session)
Definition: iddawc.c:1706
i_build_auth_url_get
int i_build_auth_url_get(struct _i_session *i_session)
Definition: iddawc.c:1908
_i_session
Definition: iddawc.h:145
i_introspect_token
int i_introspect_token(struct _i_session *i_session, json_t **j_result)
Definition: iddawc.c:2509
i_verify_id_token
int i_verify_id_token(struct _i_session *i_session)
Definition: iddawc.c:2314
i_export_session_json_t
json_t * i_export_session_json_t(struct _i_session *i_session)
Definition: iddawc.c:2627
i_get_int_parameter
uint i_get_int_parameter(struct _i_session *i_session, i_option option)
Definition: iddawc.c:1671
i_register_client
int i_register_client(struct _i_session *i_session, json_t *j_parameters, int update_session, json_t **j_result)
Definition: iddawc.c:2566
i_set_str_parameter
int i_set_str_parameter(struct _i_session *i_session, i_option option, const char *s_value)
Definition: iddawc.c:1070
i_clean_session
void i_clean_session(struct _i_session *i_session)
Definition: iddawc.c:910
i_run_auth_request
int i_run_auth_request(struct _i_session *i_session)
Definition: iddawc.c:1990
i_get_response_type
uint i_get_response_type(struct _i_session *i_session)
Definition: iddawc.c:1663
i_get_additional_parameter
const char * i_get_additional_parameter(struct _i_session *i_session, const char *s_key)
Definition: iddawc.c:1892
i_set_response_type
int i_set_response_type(struct _i_session *i_session, uint i_value)
Definition: iddawc.c:953
i_run_token_request
int i_run_token_request(struct _i_session *i_session)
Definition: iddawc.c:2094
i_load_userinfo_custom
int i_load_userinfo_custom(struct _i_session *i_session, const char *http_method, struct _u_map *additional_query, struct _u_map *additional_headers)
Definition: iddawc.c:1547
i_revoke_token
int i_revoke_token(struct _i_session *i_session)
Definition: iddawc.c:2454
i_set_additional_parameter
int i_set_additional_parameter(struct _i_session *i_session, const char *s_key, const char *s_value)
Definition: iddawc.c:1384
i_option
i_option
Definition: iddawc.h:82
i_init_session
int i_init_session(struct _i_session *i_session)
Definition: iddawc.c:831
i_get_additional_response
const char * i_get_additional_response(struct _i_session *i_session, const char *s_key)
Definition: iddawc.c:1900
i_get_str_parameter
const char * i_get_str_parameter(struct _i_session *i_session, i_option option)
Definition: iddawc.c:1778
i_load_openid_config
int i_load_openid_config(struct _i_session *i_session)
Definition: iddawc.c:1494
i_set_additional_response
int i_set_additional_response(struct _i_session *i_session, const char *s_key, const char *s_value)
Definition: iddawc.c:1396
i_export_session_str
char * i_export_session_str(struct _i_session *i_session)
Definition: iddawc.c:2773
i_import_session_str
int i_import_session_str(struct _i_session *i_session, const char *str_import)
Definition: iddawc.c:2784
i_set_int_parameter
int i_set_int_parameter(struct _i_session *i_session, i_option option, uint i_value)
Definition: iddawc.c:961
i_set_result
int i_set_result(struct _i_session *i_session, uint i_value)
Definition: iddawc.c:957