SoupAuth: libsoup Reference Manual

## SoupAuth SoupAuth — HTTP client-side authentication support |

## Functions

SoupAuth * | soup_auth_new ()
gboolean | soup_auth_update ()
gboolean | soup_auth_negotiate_supported ()
gboolean | soup_auth_is_for_proxy ()
const char * | soup_auth_get_scheme_name ()
const char * | soup_auth_get_host ()
const char * | soup_auth_get_realm ()
char * | soup_auth_get_info ()
void | soup_auth_authenticate ()
gboolean | soup_auth_can_authenticate ()
gboolean | soup_auth_is_authenticated ()
gboolean | soup_auth_is_ready ()
char * | soup_auth_get_authorization ()
GSList * | soup_auth_get_protection_space ()
void | soup_auth_free_protection_space ()

## Properties

gchar * | host | Read / Write
gboolean | is-authenticated | Read
gboolean | is-for-proxy | Read / Write
gchar * | realm | Read / Write
gchar * | scheme-name | Read

## Types and Values

| SoupAuth
#define | SOUP_TYPE_AUTH_BASIC
#define | SOUP_TYPE_AUTH_DIGEST
#define | SOUP_TYPE_AUTH_NTLM
#define | SOUP_TYPE_AUTH_NEGOTIATE
#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

## Includes

    #include <libsoup/soup.h>

## Description

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

## Functions

### 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.

#### Parameters

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.

[nullable]

### 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.

#### Parameters

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_negotiate_supported ()

    gboolean
    soup_auth_negotiate_supported (void);

Indicates whether libsoup was built with GSSAPI support. If this is `FALSE`, `SOUP_TYPE_AUTH_NEGOTIATE` will still be defined and can still be added to a SoupSession, but libsoup will never attempt to actually use this auth type.

Since: 2.54

### 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.

#### Parameters

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")

#### Parameters

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.

#### Parameters

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.)

#### Parameters

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).

#### Parameters

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.

#### Parameters

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

### soup_auth_can_authenticate ()

    gboolean
    soup_auth_can_authenticate (SoupAuth *auth);

Tests if `auth` is able to authenticate by providing credentials to the `soup_auth_authenticate()`.

#### Parameters

auth | a SoupAuth |

#### Returns

`TRUE` if `auth` is able to accept credentials.

Since: 2.54

### soup_auth_is_authenticated ()

    gboolean
    soup_auth_is_authenticated (SoupAuth *auth);

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

#### Parameters

auth | a SoupAuth |

#### Returns

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

### soup_auth_is_ready ()

    gboolean
    soup_auth_is_ready (SoupAuth *auth,
                        SoupMessage *msg);

Tests if `auth` is ready to make a request for `msg` with. For most auths, this is equivalent to `soup_auth_is_authenticated()`, but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.

#### Parameters

auth | a SoupAuth |
msg | a SoupMessage |

#### Returns

`TRUE` if `auth` is ready to make a request with.

Since: 2.42

### 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`.)

#### Parameters

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.)

#### Parameters

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]

### soup_auth_free_protection_space ()

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

Frees `space` .

[skip]

#### Parameters

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

## Types and Values

### 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_TYPE_AUTH_BASIC

    #define SOUP_TYPE_AUTH_BASIC  (soup_auth_basic_get_type ())

A GType corresponding to HTTP "Basic" authentication. SoupSessions support this by default; if you want to disable support for it, call `soup_session_remove_feature_by_type()`, passing `SOUP_TYPE_AUTH_BASIC`.

Since: 2.34

### SOUP_TYPE_AUTH_DIGEST

    #define SOUP_TYPE_AUTH_DIGEST (soup_auth_digest_get_type ())

A GType corresponding to HTTP "Digest" authentication. SoupSessions support this by default; if you want to disable support for it, call `soup_session_remove_feature_by_type()`, passing `SOUP_TYPE_AUTH_DIGEST`.

Since: 2.34

### SOUP_TYPE_AUTH_NTLM

    #define SOUP_TYPE_AUTH_NTLM   (soup_auth_ntlm_get_type ())

A GType corresponding to HTTP-based NTLM authentication. SoupSessions do not support this type by default; if you want to enable support for it, call `soup_session_add_feature_by_type()`, passing `SOUP_TYPE_AUTH_NTLM`.

Since: 2.34

### SOUP_TYPE_AUTH_NEGOTIATE

    #define SOUP_TYPE_AUTH_NEGOTIATE  (soup_auth_negotiate_get_type ())

A GType corresponding to HTTP-based GSS-Negotiate authentication. SoupSessions do not support this type by default; if you want to enable support for it, call `soup_session_add_feature_by_type()`, passing `SOUP_TYPE_AUTH_NEGOTIATE`.

This auth type will only work if libsoup was compiled with GSSAPI support; you can check `soup_auth_negotiate_supported()` to see if it was.

Since: 2.54

### SOUP_AUTH_SCHEME_NAME

    #define SOUP_AUTH_SCHEME_NAME      "scheme-name"

An alias for the “scheme-name” 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 *

Authentication host.

Owner: SoupAuth

Flags: Read / Write

Default value: NULL

### The `“is-authenticated”` property

      “is-authenticated”         gboolean

Whether or not the auth is authenticated.

Owner: SoupAuth

Flags: Read

Default value: FALSE

### The `“is-for-proxy”` property

      “is-for-proxy”             gboolean

Whether or not the auth is for a proxy server.

Owner: SoupAuth

Flags: Read / Write

Default value: FALSE

### The `“realm”` property

      “realm”                    gchar *

Authentication realm.

Owner: SoupAuth

Flags: Read / Write

Default value: NULL

### The `“scheme-name”` property

      “scheme-name”              gchar *

Authentication scheme name.

Owner: SoupAuth

Flags: Read

Default value: NULL

## See Also

SoupSession