## SoupAuth

SoupAuth — HTTP client-side authentication support

## Synopsis

    #include <libsoup/soup.h>

                        SoupAuth;
    SoupAuth *          soup_auth_new                       (GType type,
                                                             SoupMessage *msg,
                                                             const char *auth_header);
    gboolean            soup_auth_update                    (SoupAuth *auth,
                                                             SoupMessage *msg,
                                                             const char *auth_header);

    gboolean            soup_auth_is_for_proxy              (SoupAuth *auth);
    const char *        soup_auth_get_scheme_name           (SoupAuth *auth);
    const char *        soup_auth_get_host                  (SoupAuth *auth);
    const char *        soup_auth_get_realm                 (SoupAuth *auth);
    char *              soup_auth_get_info                  (SoupAuth *auth);

    void                soup_auth_authenticate              (SoupAuth *auth,
                                                             const char *username,
                                                             const char *password);
    gboolean            soup_auth_is_authenticated          (SoupAuth *auth);

    char *              soup_auth_get_authorization         (SoupAuth *auth,
                                                             SoupMessage *msg);
    GSList *            soup_auth_get_protection_space      (SoupAuth *auth,
                                                             SoupURI *source_uri);
    void                soup_auth_free_protection_space     (SoupAuth *auth,
                                                             GSList *space);

    #define             SOUP_AUTH_SCHEME_NAME
    #define             SOUP_AUTH_REALM
    #define             SOUP_AUTH_HOST
    #define             SOUP_AUTH_IS_FOR_PROXY
    #define             SOUP_AUTH_IS_AUTHENTICATED

## Object Hierarchy

      GObject
       +----SoupAuth

## Properties

      "host"                     gchar*                : Read / Write / Construct Only
      "is-authenticated"         gboolean              : Read
      "is-for-proxy"             gboolean              : Read / Write / Construct Only
      "realm"                    gchar*                : Read / Write / Construct Only
      "scheme-name"              gchar*                : Read

## Signals

      "save-password"                                  : Run First

## Description

SoupAuth objects store the authentication data associated with a given bit of web space. They are created automatically by SoupSession.

## Details

### SoupAuth

    typedef struct _SoupAuth SoupAuth;

The abstract base class for handling authentication. Specific HTTP Authentication mechanisms are implemented by its subclasses, but applications never need to be aware of the specific subclasses being used.

### soup_auth_new ()

    SoupAuth *          soup_auth_new                       (GType type,
                                                             SoupMessage *msg,
                                                             const char *auth_header);

Creates a new SoupAuth of type `type` with the information from `msg` and `auth_header`.

This is called by SoupSession; you will normally not create auths yourself.

`type` : | the type of auth to create (a subtype of SoupAuth)
`msg` : | the SoupMessage the auth is being created for
`auth_header` : | the WWW-Authenticate/Proxy-Authenticate header
Returns : | the new SoupAuth, or `NULL` if it could not be created

### soup_auth_update ()

    gboolean            soup_auth_update                    (SoupAuth *auth,
                                                             SoupMessage *msg,
                                                             const char *auth_header);

Updates `auth` with the information from `msg` and `auth_header`, possibly un-authenticating it. As with `soup_auth_new()`, this is normally only used by SoupSession.

`auth` : | a SoupAuth
`msg` : | the SoupMessage `auth` is being updated for
`auth_header` : | the WWW-Authenticate/Proxy-Authenticate header
Returns : | `TRUE` if `auth` is still a valid (but potentially unauthenticated) SoupAuth. `FALSE` if something about `auth_params` could not be parsed or incorporated into `auth` at all.

### soup_auth_is_for_proxy ()

    gboolean            soup_auth_is_for_proxy              (SoupAuth *auth);

Tests whether or not `auth` is associated with a proxy server rather than an "origin" server.

`auth` : | a SoupAuth
Returns : | `TRUE` or `FALSE`

### soup_auth_get_scheme_name ()

    const char *        soup_auth_get_scheme_name           (SoupAuth *auth);

Returns `auth`'s scheme name. (Eg, "Basic", "Digest", or "NTLM")

`auth` : | a SoupAuth
Returns : | the scheme name

### soup_auth_get_host ()

    const char *        soup_auth_get_host                  (SoupAuth *auth);

Returns the host that `auth` is associated with.

`auth` : | a SoupAuth
Returns : | the hostname

### soup_auth_get_realm ()

    const char *        soup_auth_get_realm                 (SoupAuth *auth);

Returns `auth`'s realm. This is an identifier that distinguishes separate authentication spaces on a given server, and may be some string that is meaningful to the user. (Although it is probably not localized.)

`auth` : | a SoupAuth
Returns : | the realm name

### soup_auth_get_info ()

    char *              soup_auth_get_info                  (SoupAuth *auth);

Gets an opaque identifier for `auth`, for use as a hash key or the like. SoupAuth objects from the same server with the same identifier refer to the same authentication domain (eg, the URLs associated with them take the same usernames and passwords).

`auth` : | a SoupAuth
Returns : | the identifier

### soup_auth_authenticate ()

    void                soup_auth_authenticate              (SoupAuth *auth,
                                                             const char *username,
                                                             const char *password);

Call this on an auth to authenticate it; normally this will cause the auth's message to be requeued with the new authentication info.

This does not cause the password to be saved to persistent storage; see `soup_auth_save_password()` for that.

`auth` : | a SoupAuth
`username` : | the username provided by the user or client
`password` : | the password provided by the user or client

### soup_auth_is_authenticated ()

    gboolean            soup_auth_is_authenticated          (SoupAuth *auth);

Tests if `auth` has been given a username and password

`auth` : | a SoupAuth
Returns : | `TRUE` if `auth` has been given a username and password

### soup_auth_get_authorization ()

    char *              soup_auth_get_authorization         (SoupAuth *auth,
                                                             SoupMessage *msg);

Generates an appropriate "Authorization" header for `msg`. (The session will only call this if `soup_auth_is_authenticated()` returned `TRUE`.)

`auth` : | a SoupAuth
`msg` : | the SoupMessage to be authorized
Returns : | the "Authorization" header, which must be freed.

### soup_auth_get_protection_space ()

    GSList *            soup_auth_get_protection_space      (SoupAuth *auth,
                                                             SoupURI *source_uri);

Returns a list of paths on the server which `auth` extends over. (All subdirectories of these paths are also assumed to be part of `auth`'s protection space, unless otherwise discovered not to be.)

`auth` : | a SoupAuth
`source_uri` : | the URI of the request that `auth` was generated in response to.
Returns : | the list of paths, which can be freed with `soup_auth_free_protection_space()`. [element-type utf8][transfer full utf8]

### soup_auth_free_protection_space ()

    void                soup_auth_free_protection_space     (SoupAuth *auth,
                                                             GSList *space);

Frees `space`.

`auth` : | a SoupAuth
`space` : | the return value from `soup_auth_get_protection_space()`

### SOUP_AUTH_SCHEME_NAME

    #define SOUP_AUTH_SCHEME_NAME      "scheme-name"

An alias for the "scheme" property. (The authentication scheme name.)

### SOUP_AUTH_REALM

    #define SOUP_AUTH_REALM            "realm"

An alias for the "realm" property. (The authentication realm.)

### SOUP_AUTH_HOST

    #define SOUP_AUTH_HOST             "host"

An alias for the "host" property. (The host being authenticated to.)

### SOUP_AUTH_IS_FOR_PROXY

    #define SOUP_AUTH_IS_FOR_PROXY     "is-for-proxy"

An alias for the "is-for-proxy" property. (Whether or not the auth is for a proxy server.)

### SOUP_AUTH_IS_AUTHENTICATED

    #define SOUP_AUTH_IS_AUTHENTICATED "is-authenticated"

An alias for the "is-authenticated" property. (Whether or not the auth has been authenticated.)

## Property Details

### The `"host"` property

      "host"                     gchar*                : Read / Write / Construct Only

Authentication host.

Default value: NULL

### The `"is-authenticated"` property

      "is-authenticated"         gboolean              : Read

Whether or not the auth is authenticated.

Default value: FALSE

### The `"is-for-proxy"` property

      "is-for-proxy"             gboolean              : Read / Write / Construct Only

Whether or not the auth is for a proxy server.

Default value: FALSE

### The `"realm"` property

      "realm"                    gchar*                : Read / Write / Construct Only

Authentication realm.

Default value: NULL

### The `"scheme-name"` property

      "scheme-name"              gchar*                : Read

Authentication scheme name.

Default value: NULL

## Signal Details

### The `"save-password"` signal

    void                user_function                      (SoupAuth *auth,
                                                            gchar    *username,
                                                            gchar    *password,
                                                            gpointer  user_data)      : Run First

Emitted to request that the `username`/`password` pair be saved. If the session supports password-saving, it will connect to this signal before emitting "authenticate", so that it record the password if requested by the caller.

`auth` : | the auth
`username` : | the username to save
`password` : | the password to save
`user_data` : | user data set when the signal handler was connected.

Since 2.28

## See Also

SoupSession