A challenge from a server requiring authentication from the client.


Most apps do not create authentication challenges themselves. However, you might need to create authentication challenge objects when adding support for custom networking protocols, as part of your custom URLProtocol subclasses.

Instead, your app receives authentication challenges in various URLSession, NSURLConnection, and NSURLDownload delegate methods, such as urlSession(_:task:didReceive:completionHandler:). These objects provide the information you’ll need when deciding how to handle a server’s request for authentication. At the core of that authentication challenge is a protection space that defines the type of authentication being requested, the host and port number, the networking protocol, and (where applicable) the authentication realm (a group of related URLs on the same server that share a single set of credentials).

Your app responds to authentication challenges by providing an URLCredential object. The details depend on the API you are using and on the type of challenge.

At a high level, if you’re providing the user’s credentials to a server or proxy, the proposedCredential method provides a credential that matches the criteria specified in the protection space, retrieved from the URLCredentialStorage class handling the request (assuming such a credential exists).

If the previousFailureCount method returns 0 and the proposed credential exists, the proposed credential has not yet been tried, which means you should try it. If it returns a nonzero result, then the server has rejected the proposed credential, and you should use that credential to populate a password or certificate chooser dialog, then provide a new credential. You can create password-based credentials by calling the credentialWithUser:password:persistence: method or create certificate-based credentials with the credentialWithIdentity:certificates:persistence:.

If the authentication’s protection space uses the NSURLAuthenticationMethodServerTrust authentication method, the request is asking you to verify the server’s authenticity. In this case, the proposedCredential method provides a credential based on the certificates that the server provided as part of its initial TLS handshake. Most apps should request default handling for authentication challenges based on a server trust protection space, but if you need to override the default TLS validation behavior, you can do so as described in Overriding TLS Chain Validation Correctly.

For more information about how URL sessions handle the different types of authentication challenges, see URLSession and URL Session Programming Guide.


Creating an authentication challenge instance

init(authenticationChallenge: URLAuthenticationChallenge, sender: URLAuthenticationChallengeSender)

Returns an initialized NSURLAuthenticationChallenge object copying the properties from challenge, and setting the authentication sender to sender.

init(protectionSpace: URLProtectionSpace, proposedCredential: URLCredential?, previousFailureCount: Int, failureResponse: URLResponse?, error: Error?, sender: URLAuthenticationChallengeSender)

Returns an initialized NSURLAuthenticationChallenge object for the specified protection space, credential, failure count, server response, error, and sender.

Getting authentication challenge properties

var error: Error?

The error object representing the last authentication failure.

var failureResponse: URLResponse?

The URL response object representing the last authentication failure.

var previousFailureCount: Int

The receiver’s count of failed authentication attempts.

var proposedCredential: URLCredential?

The proposed credential for this challenge.

var protectionSpace: URLProtectionSpace

The receiver’s protection space.

protocol URLAuthenticationChallengeSender

The NSURLAuthenticationChallengeSender protocol represents the interface that the sender of an authentication challenge must implement.


Inherits From

See Also

Authentication and Credentials

class URLCredential

An authentication credential consisting of authentication information specific to the type of credential and the type of persistent storage to use, if any.

class URLCredentialStorage

An object that manages the credential storage.

class URLProtectionSpace

A server or an area on a server, commonly referred to as a realm, that requires authentication.