Loading...
Searching...
No Matches
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_parse_token_response (struct _i_session *i_session, int http_status, json_t *j_response)
int | i_verify_id_token (struct _i_session *i_session)
int | i_verify_jwt_access_token (struct _i_session *i_session, const char *aud)
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_get_registration_client (struct _i_session *i_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_delete_registration_client (struct _i_session *i_session)
char * | i_generate_dpop_token (struct _i_session *i_session, const char *htm, const char *htu, time_t iat, int add_ath)
int | i_verify_dpop_proof (const char *dpop_header, const char *htm, const char *htu, time_t max_iat, const char *jkt, const char *access_token)
char * | i_generate_client_assertion (struct _i_session *i_session, const char *aud)
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)
int | i_run_ciba_request (struct _i_session *i_session)
char * | i_build_end_session_url (struct _i_session *i_session)
int | i_verify_end_session_backchannel_token (struct _i_session *i_session, const char *token)
int | i_close_session (struct _i_session *i_session, const char *sid)

## Detailed Description

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

## Function Documentation

## 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_build_end_session_url()

char * i_build_end_session_url | ( | struct _i_session * | i_session | ) |

Generates an end session url to access the single logout page

Parameters

  i_session | a reference to a struct _i_session * The session must contain an end_session_endpoint and an id_token at least If a post_logout_redirect_uri is available in the session, this will be added to the url

Returns
  a char * containing the end session url, must be i_free'd after use

## i_close_session()

int i_close_session | ( | struct _i_session * | i_session,
|  | const char * | sid
| ) |  |

Closes the current session by cleaning the following values of the session: code, refresh token, access token, id_token, nonce, userinfo, jti, device auth code, device auth user code, device auth verification uri, device auth verification uri complete, PKCE code verifier, CIBA user code, CIBA auth req id, id_token sid

Parameters

  i_session | a reference to a struct _i_session *
  sid | the session ID, this parameter is optional, although if present, the value will be checked with the session sid value, if they don't match, i_close_session will return an error and the session will not be cleaned

Returns
  I_OK on success, an error value on error

## i_delete_registration_client()

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

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

Parameters

  i_session | a reference to a struct _i_session *

Returns
  I_OK on success, an error value on error

## i_generate_client_assertion()

char * i_generate_client_assertion | ( | struct _i_session * | i_session,
|  | const char * | aud
| ) |  |

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

Parameters

  i_session | a reference to a struct _i_session *
  aud | The audience of the token, example: the token endpoint URL

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

## i_generate_dpop_token()

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

Generates a DPoP token based on the given parameters and the internal state of the struct _i_session The jti must be previously set 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
  add_ath | Add access token hash (ath) based on the access token in the i_session

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

## 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_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_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_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_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 client_secret, registration_client_uri and registration_access_token (as I_OPT_ACCESS_TOKEN)
  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_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_parse_token_response()

int i_parse_token_response | ( | struct _i_session * | i_session,
|  | int | http_status,
|  | json_t * | j_response
| ) |  |

Parses a token response in JSON format and sets the result values in the session variables

Parameters

  i_session | a reference to a struct _i_session *
  http_status | the HTTP status response
  j_response | the response body in JSON format

Returns
  I_OK on success, an error value on error

## 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_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 client_secret, registration_client_uri and registration_access_token (as I_OPT_ACCESS_TOKEN)
  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_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_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_run_ciba_request()

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

Executes a CIBA request and sets the auth_req_id, expires_in and interval in the _i_session *

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

## 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_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_dpop_proof()

int i_verify_dpop_proof | ( | const char * | dpop_header,
|  | const char * | htm,
|  | const char * | htu,
|  | time_t | max_iat,
|  | const char * | jkt,
|  | const char * | access_token
| ) |  |

Verifies the dpop_header is valid with the jkt specified

Parameters

  dpop_header | the dpop header in a serialized JWT format
  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)
  max_iat | the maximum age of the dpop, based on the claim iat, if set to 0, no expiration date will be checked
  jkt | the signature identifier specified by the access_token
  access_token | the access token linked with this proof

Returns
  I_OK on success, an error value on error

## i_verify_end_session_backchannel_token()

int i_verify_end_session_backchannel_token | ( | struct _i_session * | i_session,
|  | const char * | token
| ) |  |

Validates the end session token sent by the AS via the backchannel_logout_uri

Parameters

  i_session | a reference to a struct _i_session *
  token | the end session token to validate

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,
|  | const char * | aud
| ) |  |

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 *
  aud | the aud claim to verify, set to NULL to ignore aud claim

Returns
  I_OK on success, an error value on error