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