Iddawc: Run OAuth2 or OIDC requests

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

Functions
Run OAuth2 or OIDC requests

## Functions
int | i_get_openid_config (struct _i_session *i_session)
int | i_build_auth_url_get (struct _i_session *i_session)
int | i_run_auth_request (struct _i_session *i_session)
int | i_parse_redirect_to (struct _i_session *i_session)
int | i_run_token_request (struct _i_session *i_session)
int | i_verify_id_token (struct _i_session *i_session)
int | i_verify_jwt_access_token (struct _i_session *i_session)
int | i_get_userinfo (struct _i_session *i_session, int get_jwt)
int | i_get_userinfo_custom (struct _i_session *i_session, const char *http_method, struct _u_map *additional_query, struct _u_map *additional_headers)
int | i_get_token_introspection (struct _i_session *i_session, json_t **j_result, int authentication, int get_jwt)
int | i_revoke_token (struct _i_session *i_session, int authentication)
int | i_register_client (struct _i_session *i_session, json_t *j_parameters, int update_session, json_t **j_result)
int | i_manage_registration_client (struct _i_session *i_session, json_t *j_parameters, int update_session, json_t **j_result)
int | i_get_registration_client (struct _i_session *i_session, json_t **j_result)
char * | i_generate_dpop_token (struct _i_session *i_session, const char *htm, const char *htu, time_t iat)
int | i_perform_resource_service_request (struct _i_session *i_session, struct _u_request *http_request, struct _u_response *http_response, int refresh_if_expired, int bearer_type, int use_dpop, time_t dpop_iat)
int | i_run_par_request (struct _i_session *i_session)
int | i_run_device_auth_request (struct _i_session *i_session)

## Detailed Description

Run auth, token, userinfo, introspect, revoke or register requests

## Function Documentation

## ◆ i_get_openid_config()

int i_get_openid_config | ( | struct _i_session * | i_session | ) |

Loads and parse the openid_config endpoint, and sets the parameter values accordingly

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_build_auth_url_get()

int i_build_auth_url_get | ( | struct _i_session * | i_session | ) |

Builds the url to GET the auth endpoint sets the result to parameter I_OPT_REDIRECT_TO

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_run_auth_request()

int i_run_auth_request | ( | struct _i_session * | i_session | ) |

Executes an auth request using the implicit endpoint and sets the result values in the session variables

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_parse_redirect_to()

int i_parse_redirect_to | ( | struct _i_session * | i_session | ) |

Parses the redirect_uri given by the oauth2 server in the implicit flow The redirect_uri may contain a code, a token, an id_token, or an error Fills the session parameters with the values given in the redirect_uri

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_run_token_request()

int i_run_token_request | ( | struct _i_session * | i_session | ) |

Executes a token request using the implicit endpoint and sets the result values in the session variables

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_verify_id_token()

int i_verify_id_token | ( | struct _i_session * | i_session | ) |

Validates the id_token signature and content if necessary

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_verify_jwt_access_token()

int i_verify_jwt_access_token | ( | struct _i_session * | i_session | ) |

Validates the access_token signature and content if necessary According to OAuth 2.0 Access Token JWT Profile Draft 12 https://datatracker.ietf.org/doc/html/draft-ietf-oauth-access-token-jwt-12

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_get_userinfo()

int i_get_userinfo | ( | struct _i_session * | i_session,
|  | int | get_jwt
| ) |  |

Loads the userinfo endpoint using the access_token if the result is a JWT, validate the signature and/or decrypt the token sets the result to i_session->userinfo as char * and i_session->j_userinfo as json_t * if the result is in JSON format

Parameters

  i_session | a reference to a struct _i_session *
  get_jwt | Request result as a JWT

Returns
  I_OK on success, an error value on error

## ◆ i_get_userinfo_custom()

int i_get_userinfo_custom | ( | struct _i_session * | i_session,
|  | const char * | http_method,
|  | struct _u_map * | additional_query,
|  | struct _u_map * | additional_headers
| ) |  |

Loads the userinfo endpoint using the access_token with custom parameters if the result is a JWT, validate the signature and/or decrypt the token sets the result to i_session->userinfo as char * and i_session->j_userinfo as json_t * if the result is in JSON format

Parameters

  i_session | a reference to a struct _i_session *
  http_method | http method to use, values available are 'GET' or 'POST'
  additional_query | set of additional parameters to add to the url query
  additional_headers | set of additional parameters to add to the request header

Returns
  I_OK on success, an error value on error

## ◆ i_get_token_introspection()

int i_get_token_introspection | ( | struct _i_session * | i_session,
|  | json_t ** | j_result,
|  | int | authentication,
|  | int | get_jwt
| ) |  |

Loads the introspection endpoint for the access_token_target Using the access_token for authentication

Parameters

  i_session | a reference to a struct _i_session *
  j_result | if not NULL, set an allocated json_t * object with the endpoint result
  authentication | authentication type types available are I_INTROSPECT_REVOKE_AUTH_NONE, I_INTROSPECT_REVOKE_AUTH_ACCESS_TOKEN, I_INTROSPECT_REVOKE_AUTH_CLIENT_TARGET
  get_jwt | Request result as a JWT

Returns
  I_OK on success and if the access_token_target is valid, I_ERROR_UNAUTHORIZED if the access_token_target is invalid, another error value on error

## ◆ i_revoke_token()

int i_revoke_token | ( | struct _i_session * | i_session,
|  | int | authentication
| ) |  |

Loads the revocation endpoint for the access_token_target Using the access_token for authentication

Parameters

  i_session | a reference to a struct _i_session *
  authentication | authentication type types available are I_INTROSPECT_REVOKE_AUTH_NONE, I_INTROSPECT_REVOKE_AUTH_ACCESS_TOKEN, I_INTROSPECT_REVOKE_AUTH_CLIENT_TARGET

Returns
  I_OK on success, an error value on error

## ◆ i_register_client()

int i_register_client | ( | struct _i_session * | i_session,
|  | json_t * | j_parameters,
|  | int | update_session,
|  | json_t ** | j_result
| ) |  |

Register a new client using the dynamic registration endpoint Using the access_token for authentication if set

Parameters

  i_session | a reference to a struct _i_session *
  j_parameters | a json_t * object containing the client metadata The metadata content depends on the registration endpoint but at least the parameter redirect_uris (array of string) is required to register a new client
  update_session | if the registration is succesfull, update the session with the new client_id and client_secret
  j_result | if not NULL, set an allocated json_t * object with the endpoint result

Returns
  I_OK on success, an error value on error

## ◆ i_manage_registration_client()

int i_manage_registration_client | ( | struct _i_session * | i_session,
|  | json_t * | j_parameters,
|  | int | update_session,
|  | json_t ** | j_result
| ) |  |

Manages a client registration using the dynamic registration endpoint Using the access_token for authentication

Parameters

  i_session | a reference to a struct _i_session *
  j_parameters | a json_t * object containing the client metadata The metadata content depends on the registration endpoint but at least the parameter redirect_uris (array of string) is required to register a new client
  update_session | if the registration is succesfull, update the session with the new client_id and client_secret
  j_result | if not NULL, set an allocated json_t * object with the endpoint result

Returns
  I_OK on success, an error value on error

## ◆ i_get_registration_client()

int i_get_registration_client | ( | struct _i_session * | i_session,
|  | json_t ** | j_result
| ) |  |

Gets a client registration using the dynamic registration endpoint Using the access_token for authentication

Parameters

  i_session | a reference to a struct _i_session *
  j_result | if not NULL, set an allocated json_t * object with the endpoint result

Returns
  I_OK on success, an error value on error

## ◆ i_generate_dpop_token()

char* i_generate_dpop_token | ( | struct _i_session * | i_session,
|  | const char * | htm,
|  | const char * | htu,
|  | time_t | iat
| ) |  |

Generates a DPoP token based on the given parameters and the internal state of the struct _i_session The jti must be previously generated via I_OPT_TOKEN_JTI or generated via I_OPT_TOKEN_JTI_GENERATE

Parameters

  i_session | a reference to a struct _i_session *
  htm | The htm claim value, the HTTP method used to access the protected resource (GET, POST, PATCH, etc.)
  htu | The htu claim value, the HTTP url used to access the protected resource (ex: https://resource.tld/object)
  iat | the iat claim value, the epoch time value when the DPoP token must be set. If 0, the current time will be used

Returns
  a char * containing the DPoP token signed, must be i_free'd after use

## ◆ i_perform_resource_service_request()

int i_perform_resource_service_request | ( | struct _i_session * | i_session,
|  | struct _u_request * | http_request,
|  | struct _u_response * | http_response,
|  | int | refresh_if_expired,
|  | int | bearer_type,
|  | int | use_dpop,
|  | time_t | dpop_iat
| ) |  |

Sends an HTTP request to a REST API using the access token to authenticate This functions uses ulfius' function ulfius_send_http_request It will add the i_session's access token to the request As well as a DPoP token if required

Parameters

  i_session | a reference to a struct _i_session *, mandatory
  http_request | the request parameters, will store all the request data (method, url, headers, body parameters, etc.), mandatory
  http_response | the response parameters, will store all the response data (status, headers, body response, etc.), may be NULL
  refresh_if_expired | if set to true, the access token will be refreshed if expired
  bearer_type | How the access token will be provided to the resource server options available are: I_BEARER_TYPE_HEADER, I_BEARER_TYPE_BODY, I_BEARER_TYPE_URL
  use_dpop | set this flag to 1 if you want to send the DPoP header in the request The jti must be previously generated via I_OPT_TOKEN_JTI or generated via I_OPT_TOKEN_JTI_GENERATE
  dpop_iat | the iat claim value, the epoch time value when the DPoP token must be set. If 0, the current time will be used

Returns
  I_OK on success, an error value on error

## ◆ i_run_par_request()

int i_run_par_request | ( | struct _i_session * | i_session | ) |

Executes a pushed authorization request and sets the values I_OPT_PUSHED_AUTH_REQ_URI and I_OPT_PUSHED_AUTH_REQ_EXPIRES_IN on success

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## ◆ i_run_device_auth_request()

int i_run_device_auth_request | ( | struct _i_session * | i_session | ) |

Executes a device authorization request and sets the code, user code and verification uri in the _i_session *

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error