WebKitAuthenticationRequest: WPE Reference Manual

## WebKitAuthenticationRequest WebKitAuthenticationRequest — Represents an authentication request |

## Functions

void | webkit_authentication_request_authenticate ()
void | webkit_authentication_request_cancel ()
gboolean | webkit_authentication_request_can_save_credentials ()
void | webkit_authentication_request_set_can_save_credentials ()
const gchar * | webkit_authentication_request_get_host ()
guint | webkit_authentication_request_get_port ()
WebKitSecurityOrigin * | webkit_authentication_request_get_security_origin ()
gboolean | webkit_authentication_request_is_retry ()
WebKitCredential * | webkit_authentication_request_get_proposed_credential ()
void | webkit_authentication_request_set_proposed_credential ()
const gchar * | webkit_authentication_request_get_realm ()
WebKitAuthenticationScheme | webkit_authentication_request_get_scheme ()
GTlsPasswordFlags | webkit_authentication_request_get_certificate_pin_flags ()
gboolean | webkit_authentication_request_is_for_proxy ()
WebKitCredential * | webkit_credential_new ()
WebKitCredential * | webkit_credential_new_for_certificate_pin ()
WebKitCredential * | webkit_credential_new_for_certificate ()
WebKitCredential * | webkit_credential_copy ()
void | webkit_credential_free ()
const gchar * | webkit_credential_get_password ()
WebKitCredentialPersistence | webkit_credential_get_persistence ()
const gchar * | webkit_credential_get_username ()
gboolean | webkit_credential_has_password ()
GTlsCertificate * | webkit_credential_get_certificate ()

## Signals

void | authenticated | Run Last
void | cancelled | Run Last

## Types and Values

struct | WebKitAuthenticationRequest
enum | WebKitAuthenticationScheme
| WebKitCredential
enum | WebKitCredentialPersistence

## Object Hierarchy

        GBoxed
        ╰── WebKitCredential
        GObject
        ╰── WebKitAuthenticationRequest

## Description

Whenever a client attempts to load a page protected by HTTP authentication, credentials will need to be provided to authorize access. To allow the client to decide how it wishes to handle authentication, WebKit will fire a “authenticate” signal with a WebKitAuthenticationRequest object to provide client side authentication support. Credentials are exposed through the WebKitCredential object.

In case the client application does not wish to handle this signal WebKit will provide a default handler. To handle authentication asynchronously, simply increase the reference count of the WebKitAuthenticationRequest object.

## Functions

### webkit_authentication_request_authenticate ()

    void
    webkit_authentication_request_authenticate
                                   (WebKitAuthenticationRequest *request,
                                    WebKitCredential *credential);

Authenticate the WebKitAuthenticationRequest using the WebKitCredential supplied. To continue without credentials, pass `NULL` as `credential` .

#### Parameters

request | a WebKitAuthenticationRequest |
credential | A WebKitCredential, or `NULL`. | [transfer none][allow-none]

Since: 2.2

### webkit_authentication_request_cancel ()

    void
    webkit_authentication_request_cancel (WebKitAuthenticationRequest *request);

Cancel the authentication challenge. This will also cancel the page loading and result in a “load-failed” signal with a WebKitNetworkError of type `WEBKIT_NETWORK_ERROR_CANCELLED` being emitted.

#### Parameters

request | a WebKitAuthenticationRequest |

Since: 2.2

### webkit_authentication_request_can_save_credentials ()

    gboolean
    webkit_authentication_request_can_save_credentials
                                   (WebKitAuthenticationRequest *request);

Determine whether the authentication method associated with this WebKitAuthenticationRequest should allow the storage of credentials. This will return `FALSE` if WebKit doesn't support credential storing, if private browsing is enabled, or if persistent credential storage has been disabled in WebKitWebsiteDataManager, unless credentials saving has been explicitly enabled with `webkit_authentication_request_set_can_save_credentials()`.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

`TRUE` if WebKit can store credentials or `FALSE` otherwise.

Since: 2.2

### webkit_authentication_request_set_can_save_credentials ()

    void
    webkit_authentication_request_set_can_save_credentials
                                   (WebKitAuthenticationRequest *request,
                                    gboolean enabled);

Set whether the authentication method associated with `request` should allow the storage of credentials. This should be used by applications handling their own credentials storage to indicate that it should be supported even when internal credential storage is disabled or unsupported. Note that storing of credentials will not be allowed on ephemeral sessions in any case.

#### Parameters

request | a WebKitAuthenticationRequest |
enabled | value to set |

Since: 2.30

### webkit_authentication_request_get_host ()

    const gchar *
    webkit_authentication_request_get_host
                                   (WebKitAuthenticationRequest *request);

Get the host that this authentication challenge is applicable to.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

The host of `request` .

Since: 2.2

### webkit_authentication_request_get_port ()

    guint
    webkit_authentication_request_get_port
                                   (WebKitAuthenticationRequest *request);

Get the port that this authentication challenge is applicable to.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

The port of `request` .

Since: 2.2

### webkit_authentication_request_get_security_origin ()

    WebKitSecurityOrigin *
    webkit_authentication_request_get_security_origin
                                   (WebKitAuthenticationRequest *request);

Get the WebKitSecurityOrigin that this authentication challenge is applicable to.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

a newly created WebKitSecurityOrigin.

[transfer full]

Since: 2.30

### webkit_authentication_request_is_retry ()

    gboolean
    webkit_authentication_request_is_retry
                                   (WebKitAuthenticationRequest *request);

Determine whether this this is a first attempt or a retry for this authentication challenge.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

`TRUE` if authentication attempt is a retry or `FALSE` otherwise.

Since: 2.2

### webkit_authentication_request_get_proposed_credential ()

    WebKitCredential *
    webkit_authentication_request_get_proposed_credential
                                   (WebKitAuthenticationRequest *request);

Get the WebKitCredential of the proposed authentication challenge that was stored from a previous session. The client can use this directly for authentication or construct their own WebKitCredential.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

A WebKitCredential encapsulating credential details or `NULL` if there is no stored credential.

[transfer full]

Since: 2.2

### webkit_authentication_request_set_proposed_credential ()

    void
    webkit_authentication_request_set_proposed_credential
                                   (WebKitAuthenticationRequest *request,
                                    WebKitCredential *credential);

Set the WebKitCredential of the proposed authentication challenge that was stored from a previous session. This should only be used by applications handling their own credential storage. (When using the default WebKit credential storage, `webkit_authentication_request_get_proposed_credential()` already contains previously-stored credentials.) Passing a `NULL` `credential` will clear the proposed credential.

#### Parameters

request | a WebKitAuthenticationRequest |
credential | a WebKitCredential, or `NULL` |

Since: 2.30

### webkit_authentication_request_get_realm ()

    const gchar *
    webkit_authentication_request_get_realm
                                   (WebKitAuthenticationRequest *request);

Get the realm that this authentication challenge is applicable to.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

The realm of `request` .

Since: 2.2

### webkit_authentication_request_get_scheme ()

    WebKitAuthenticationScheme
    webkit_authentication_request_get_scheme
                                   (WebKitAuthenticationRequest *request);

Get the authentication scheme of the authentication challenge.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

The WebKitAuthenticationScheme of `request` .

Since: 2.2

### webkit_authentication_request_get_certificate_pin_flags ()

    GTlsPasswordFlags
    webkit_authentication_request_get_certificate_pin_flags
                                   (WebKitAuthenticationRequest *request);

Get the GTlsPasswordFlags of the `WEBKIT_AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE_PIN_REQUESTED` authentication challenge.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

a GTlsPasswordFlags

Since: 2.34

### webkit_authentication_request_is_for_proxy ()

    gboolean
    webkit_authentication_request_is_for_proxy
                                   (WebKitAuthenticationRequest *request);

Determine whether the authentication challenge is associated with a proxy server rather than an "origin" server.

#### Parameters

request | a WebKitAuthenticationRequest |

#### Returns

`TRUE` if authentication is for a proxy or `FALSE` otherwise.

Since: 2.2

### webkit_credential_new ()

    WebKitCredential *
    webkit_credential_new (const gchar *username,
                           const gchar *password,
                           WebKitCredentialPersistence persistence);

Create a new credential from the provided username, password and persistence mode.

#### Parameters

username | The username for the new credential |
password | The password for the new credential |
persistence | The WebKitCredentialPersistence of the new credential |

#### Returns

A WebKitCredential.

[transfer full]

Since: 2.2

### webkit_credential_new_for_certificate_pin ()

    WebKitCredential *
    webkit_credential_new_for_certificate_pin
                                   (const gchar *pin,
                                    WebKitCredentialPersistence persistence);

Create a new credential from the provided PIN and persistence mode. Note that `WEBKIT_CREDENTIAL_PERSISTENCE_PERMANENT` is not supported for certificate pin credentials.

#### Parameters

pin | The PIN for the new credential |
persistence | The WebKitCredentialPersistence of the new credential |

#### Returns

A WebKitCredential.

[transfer full]

Since: 2.34

### webkit_credential_new_for_certificate ()

    WebKitCredential *
    webkit_credential_new_for_certificate (GTlsCertificate *certificate,
                                           WebKitCredentialPersistence persistence);

Create a new credential from the `certificate` and persistence mode. Note that `WEBKIT_CREDENTIAL_PERSISTENCE_PERMANENT` is not supported for certificate credentials.

#### Parameters

certificate | The GTlsCertificate, or `NULL`. | [nullable]
persistence | The WebKitCredentialPersistence of the new credential |

#### Returns

A WebKitCredential.

[transfer full]

Since: 2.34

### webkit_credential_copy ()

    WebKitCredential *
    webkit_credential_copy (WebKitCredential *credential);

Make a copy of the WebKitCredential.

#### Parameters

credential | a WebKitCredential |

#### Returns

A copy of passed in WebKitCredential.

[transfer full]

Since: 2.2

### webkit_credential_free ()

    void
    webkit_credential_free (WebKitCredential *credential);

Free the WebKitCredential.

#### Parameters

credential | A WebKitCredential |

Since: 2.2

### webkit_credential_get_password ()

    const gchar *
    webkit_credential_get_password (WebKitCredential *credential);

Get the password currently held by this WebKitCredential.

#### Parameters

credential | a WebKitCredential |

#### Returns

The password stored in the WebKitCredential.

Since: 2.2

### webkit_credential_get_persistence ()

    WebKitCredentialPersistence
    webkit_credential_get_persistence (WebKitCredential *credential);

Get the persistence mode currently held by this WebKitCredential.

#### Parameters

credential | a WebKitCredential |

#### Returns

The WebKitCredentialPersistence stored in the WebKitCredential.

Since: 2.2

### webkit_credential_get_username ()

    const gchar *
    webkit_credential_get_username (WebKitCredential *credential);

Get the username currently held by this WebKitCredential.

#### Parameters

credential | a WebKitCredential |

#### Returns

The username stored in the WebKitCredential.

Since: 2.2

### webkit_credential_has_password ()

    gboolean
    webkit_credential_has_password (WebKitCredential *credential);

Determine whether this credential has a password stored.

#### Parameters

credential | a WebKitCredential |

#### Returns

`TRUE` if the credential has a password or `FALSE` otherwise.

Since: 2.2

### webkit_credential_get_certificate ()

    GTlsCertificate *
    webkit_credential_get_certificate (WebKitCredential *credential);

Get the certificate currently held by this WebKitCredential.

#### Parameters

credential | a WebKitCredential |

#### Returns

a GTlsCertificate, or `NULL`.

[transfer none]

Since: 2.34

## Types and Values

### struct WebKitAuthenticationRequest

    struct WebKitAuthenticationRequest;

### enum WebKitAuthenticationScheme

Enum values representing the authentication scheme.

#### Members

WEBKIT_AUTHENTICATION_SCHEME_DEFAULT | The default authentication scheme of WebKit. |
WEBKIT_AUTHENTICATION_SCHEME_HTTP_BASIC | Basic authentication scheme as defined in RFC 2617. |
WEBKIT_AUTHENTICATION_SCHEME_HTTP_DIGEST | Digest authentication scheme as defined in RFC 2617. |
WEBKIT_AUTHENTICATION_SCHEME_HTML_FORM | HTML Form authentication. |
WEBKIT_AUTHENTICATION_SCHEME_NTLM | NTLM Microsoft proprietary authentication scheme. |
WEBKIT_AUTHENTICATION_SCHEME_NEGOTIATE | Negotiate (or SPNEGO) authentication scheme as defined in RFC 4559. |
WEBKIT_AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE_REQUESTED | Client Certificate Authentication (see RFC 2246). |
WEBKIT_AUTHENTICATION_SCHEME_SERVER_TRUST_EVALUATION_REQUESTED | Server Trust Authentication. |
WEBKIT_AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE_PIN_REQUESTED | Client certificate PIN required for use. Since: 2.34 |
WEBKIT_AUTHENTICATION_SCHEME_UNKNOWN | Authentication scheme unknown. |

Since: 2.2

### WebKitCredential

    typedef struct _WebKitCredential WebKitCredential;

### enum WebKitCredentialPersistence

Enum values representing the duration for which a credential persists.

#### Members

WEBKIT_CREDENTIAL_PERSISTENCE_NONE | Credential does not persist |
WEBKIT_CREDENTIAL_PERSISTENCE_FOR_SESSION | Credential persists for session only |
WEBKIT_CREDENTIAL_PERSISTENCE_PERMANENT | Credential persists permanently |

Since: 2.2

## Signal Details

### The `“authenticated”` signal

    void
    user_function (WebKitAuthenticationRequest *request,
                   WebKitCredential            *credential,
                   gpointer                     user_data)

This signal is emitted when the user authentication request succeeded. Applications handling their own credential storage should connect to this signal to save the credentials.

#### Parameters

request | the WebKitAuthenticationRequest |
credential | the WebKitCredential accepted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.30

### The `“cancelled”` signal

    void
    user_function (WebKitAuthenticationRequest *request,
                   gpointer                     user_data)

This signal is emitted when the user authentication request is cancelled. It allows the application to dismiss its authentication dialog in case of page load failure for example.

#### Parameters

request | the WebKitAuthenticationRequest |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.2

## See Also

WebKitWebView