NSURLAuthenticationChallenge Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.2 with Safari 1.0 installed.
Available in OS X v10.2.7 and later.
Companion guide
Declared in
NSURLAuthenticationChallenge.h
Related sample code

Overview

NSURLAuthenticationChallenge encapsulates 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 NSURLProtocol subclasses.

Instead, your app receives authentication challenges in various NSURLSession, NSURLConnection, and NSURLDownload delegate methods, such as URLSession:task:didReceiveChallenge: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 NSURLCredential 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 NSURLCredentialStorage 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 NSURLSession Class Reference and URL Loading System Programming Guide.

Tasks

Creating an Authentication Challenge Instance

Getting Authentication Challenge Properties

Instance Methods

error

Returns the NSError object representing the last authentication failure.

- (NSError *)error
Discussion

This method returns nil if the protocol doesn’t use errors to indicate an authentication failure.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLAuthenticationChallenge.h

failureResponse

Returns the NSURLResponse object representing the last authentication failure.

- (NSURLResponse *)failureResponse
Discussion

This method returns nil if the protocol doesn’t use responses to indicate an authentication failure.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
NSURLAuthenticationChallenge.h

initWithAuthenticationChallenge:sender:

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

- (id)initWithAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge sender:(id < NSURLAuthenticationChallengeSender >)sender
Parameters
challenge

The challenge that you want to copy.

sender

The sender that you want to use for the new object. Typically, the sender is the instance of your custom NSURLProtocol subclass that called this method.

Discussion

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 NSURLProtocol subclasses.

When subclassing an existing NSURLProtocol subclass, this method lets you modify challenges issued by the existing class so that your subclass receives any responses to those challenges.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLAuthenticationChallenge.h

initWithProtectionSpace:proposedCredential:previousFailureCount:failureResponse:error:sender:

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

- (id)initWithProtectionSpace:(NSURLProtectionSpace *)space proposedCredential:(NSURLCredential *)credential previousFailureCount:(NSInteger)count failureResponse:(NSURLResponse *)response error:(NSError *)error sender:(id < NSURLAuthenticationChallengeSender >)sender
Parameters
space

The protection space for the URL challenge. This provides additional information about the authentication request, such as the host, port, authentication realm, and so on.

credential

The proposed credential, or nil.

count

The total number of previous failures for this request, including failures for other protection spaces.

response

An NSURLResponse object containing the server response that caused you to generate an authentication challenge, or nil if no response object is applicable to the challenge.

error

An NSError object describing the authentication failure, or nil if it is not applicable to the challenge.

sender

The object that initiated the authentication challenge (typically, the object that called this method).

Discussion

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 NSURLProtocol subclasses.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLAuthenticationChallenge.h

previousFailureCount

Returns the receiver’s count of failed authentication attempts.

- (NSInteger)previousFailureCount
Discussion

The previous failure count includes failures from all protection spaces, not just the current one.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLAuthenticationChallenge.h

proposedCredential

Returns the proposed credential for this challenge.

- (NSURLCredential *)proposedCredential
Discussion

This method returns nil if there is no default credential for this challenge.

If you have previously attempted to authenticate and failed, this method returns the most recent failed credential.

If the proposed credential is not nil and returns YES when you call its hasPassword method, then the credential is ready to use as-is. If the proposed credential’s hasPassword method returns NO, then the credential provides a default user name, and the client must prompt the user for a corresponding password.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLAuthenticationChallenge.h

protectionSpace

Returns the receiver’s protection space.

- (NSURLProtectionSpace *)protectionSpace
Discussion

A protection space object provides additional information about the authentication request, such as the host, port, authentication realm, and so on. The protection space also tells you whether the authentication challenge is asking you to provide the user’s credentials or to verify the TLS credentials provided by the server.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLAuthenticationChallenge.h

sender

Returns the receiver’s sender.

Discussion

The sender is typically an instance of an NSURLProtocol subclass that initially received the authentication challenge.

If you are using the NSURLSession API, this value is purely informational, because you must respond to authentication challenges by passing constants to the provided completion handler blocks.

However, if you are using the NSURLConnection or NSURLDownload API, in your authentication handler delegate method, you respond to authentication challenges by calling methods defined in the NSURLAuthenticationChallengeSender protocol on this sender object after you finish processing the authentication challenge.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Related Sample Code
Declared In
NSURLAuthenticationChallenge.h