AppAuth
Instance Methods | Class Methods | Properties | List of all members
OIDAuthState Class Reference

A convenience class that retains the auth state between OIDAuthorizationResponses and OIDTokenResponses. More...

#import <OIDAuthState.h>

Inheritance diagram for OIDAuthState:

Instance Methods

(instancetype) - initWithAuthorizationResponse:
 Creates an auth state from an authorization response. More...
 
(instancetype) - initWithAuthorizationResponse:tokenResponse:
 Creates an auth state from an authorization and token response. More...
 
(instancetype) - initWithRegistrationResponse:
 Creates an auth state from an registration response. More...
 
(instancetype) - initWithAuthorizationResponse:tokenResponse:registrationResponse:
 Creates an auth state from an authorization, token and registration response. More...
 
(void) - updateWithAuthorizationResponse:error:
 Updates the authorization state based on a new authorization response. More...
 
(void) - updateWithTokenResponse:error:
 Updates the authorization state based on a new token response. More...
 
(void) - updateWithRegistrationResponse:
 Updates the authorization state based on a new registration response. More...
 
(void) - updateWithAuthorizationError:
 Updates the authorization state based on an authorization error. More...
 
(void) - performActionWithFreshTokens:
 Calls the block with a valid access token (refreshing it first, if needed), or if a refresh was needed and failed, with the error that caused it to fail. More...
 
(void) - performActionWithFreshTokens:additionalRefreshParameters:
 Calls the block with a valid access token (refreshing it first, if needed), or if a refresh was needed and failed, with the error that caused it to fail. More...
 
(void) - performActionWithFreshTokens:additionalRefreshParameters:dispatchQueue:
 Calls the block with a valid access token (refreshing it first, if needed), or if a refresh was needed and failed, with the error that caused it to fail. More...
 
(void) - setNeedsTokenRefresh
 Forces a token refresh the next time performActionWithFreshTokens: is called, even if the current tokens are considered valid.
 
(nullable OIDTokenRequest *) - tokenRefreshRequest
 Creates a token request suitable for refreshing an access token. More...
 
(nullable OIDTokenRequest *) - tokenRefreshRequestWithAdditionalParameters:
 Creates a token request suitable for refreshing an access token. More...
 

Class Methods

(id< OIDExternalUserAgentSession >) + authStateByPresentingAuthorizationRequest:externalUserAgent:callback:
 Convenience method to create a OIDAuthState by presenting an authorization request and performing the authorization code exchange in the case of code flow requests. For the hybrid flow, the caller should validate the id_token and c_hash, then perform the token request (performTokenRequest:callback: (OIDAuthorizationService)) and update the OIDAuthState with the results (updateWithTokenResponse:error:). More...
 
(id< OIDExternalUserAgentSession >) + authStateByPresentingAuthorizationRequest:presentingViewController:callback:
 Convenience method to create a OIDAuthState by presenting an authorization request and performing the authorization code exchange in the case of code flow requests. For the hybrid flow, the caller should validate the id_token and c_hash, then perform the token request (performTokenRequest:callback: (OIDAuthorizationService)) and update the OIDAuthState with the results (updateWithTokenResponse:error:). More...
 

Properties

NSString * refreshToken
 The most recent refresh token received from the server. @discussion Rather than using this property directly, you should call performActionWithFreshTokens:. More...
 
NSString * scope
 The scope of the current authorization grant. @discussion This represents the latest scope returned by the server and may be a subset of the scope that was initially granted. More...
 
OIDAuthorizationResponselastAuthorizationResponse
 The most recent authorization response used to update the authorization state. For the implicit flow, this will contain the latest access token.
 
OIDTokenResponselastTokenResponse
 The most recent token response used to update this authorization state. This will contain the latest access token.
 
OIDRegistrationResponselastRegistrationResponse
 The most recent registration response used to update this authorization state. This will contain the latest client credentials.
 
NSError * authorizationError
 The authorization error that invalidated this OIDAuthState. @discussion The authorization error encountered by OIDAuthState or set by the user via updateWithAuthorizationError: that invalidated this OIDAuthState. Authorization errors from OIDAuthState will always have a domain of OIDOAuthAuthorizationErrorDomain or OIDOAuthTokenErrorDomain. Note: that after unarchiving the OIDAuthState object, the NSError.userInfo property of this error will be nil.
 
BOOL isAuthorized
 Returns YES if the authorization state is not known to be invalid. @discussion Returns YES if no OAuth errors have been received, and the last call resulted in a successful access token or id token. This does not mean that the access is fresh - just that it was valid the last time it was used. Note that network and other transient errors do not invalidate the authorized state. If NO, you should authenticate the user again, using a fresh authorization request. Invalid OIDAuthState objects may still be useful in that case, to hint at the previously authorized user and streamline the re-authentication experience.
 
id< OIDAuthStateChangeDelegatestateChangeDelegate
 The OIDAuthStateChangeDelegate delegate. @discussion Use the delegate to observe state changes (and update storage) as well as error states.
 
id< OIDAuthStateErrorDelegateerrorDelegate
 The OIDAuthStateErrorDelegate delegate. @discussion Use the delegate to observe state changes (and update storage) as well as error states.
 

Detailed Description

A convenience class that retains the auth state between OIDAuthorizationResponses and OIDTokenResponses.

Method Documentation

◆ authStateByPresentingAuthorizationRequest:externalUserAgent:callback:()

+ (id<OIDExternalUserAgentSession>) authStateByPresentingAuthorizationRequest: (OIDAuthorizationRequest *)  authorizationRequest
externalUserAgent: (id< OIDExternalUserAgent >)  externalUserAgent
callback: (OIDAuthStateAuthorizationCallback callback 

Convenience method to create a OIDAuthState by presenting an authorization request and performing the authorization code exchange in the case of code flow requests. For the hybrid flow, the caller should validate the id_token and c_hash, then perform the token request (performTokenRequest:callback: (OIDAuthorizationService)) and update the OIDAuthState with the results (updateWithTokenResponse:error:).

Parameters
authorizationRequestThe authorization request to present.
externalUserAgentA external user agent that can present an external user-agent request.
callbackThe method called when the request has completed or failed.
Returns
A OIDExternalUserAgentSession instance which will terminate when it receives a cancel (OIDExternalUserAgentSession-p) message, or after processing a resumeExternalUserAgentFlowWithURL: (OIDExternalUserAgentSession-p) message.

◆ authStateByPresentingAuthorizationRequest:presentingViewController:callback:()

+ (id<OIDExternalUserAgentSession>) authStateByPresentingAuthorizationRequest: (OIDAuthorizationRequest *)  authorizationRequest
presentingViewController: (UIViewController *)  presentingViewController
callback: (OIDAuthStateAuthorizationCallback callback 

Convenience method to create a OIDAuthState by presenting an authorization request and performing the authorization code exchange in the case of code flow requests. For the hybrid flow, the caller should validate the id_token and c_hash, then perform the token request (performTokenRequest:callback: (OIDAuthorizationService)) and update the OIDAuthState with the results (updateWithTokenResponse:error:).

Parameters
authorizationRequestThe authorization request to present.
presentingViewControllerThe view controller from which to present the SFSafariViewController. On iOS 13, the window of this UIViewController is used as the ASPresentationAnchor.
callbackThe method called when the request has completed or failed.
Returns
A OIDExternalUserAgentSession instance which will terminate when it receives a cancel (OIDExternalUserAgentSession-p) message, or after processing a resumeExternalUserAgentFlowWithURL: (OIDExternalUserAgentSession-p) message.

Provided by category OIDAuthState(IOS).

◆ initWithAuthorizationResponse:()

- (instancetype) initWithAuthorizationResponse: (OIDAuthorizationResponse *)  authorizationResponse

Creates an auth state from an authorization response.

Parameters
authorizationResponseThe authorization response.

◆ initWithAuthorizationResponse:tokenResponse:()

- (instancetype) initWithAuthorizationResponse: (OIDAuthorizationResponse *)  authorizationResponse
tokenResponse: (nullable OIDTokenResponse *)  tokenResponse 

Creates an auth state from an authorization and token response.

Parameters
authorizationResponseThe authorization response.
tokenResponseThe token response.

◆ initWithAuthorizationResponse:tokenResponse:registrationResponse:()

- (instancetype) initWithAuthorizationResponse: (nullable OIDAuthorizationResponse *)  authorizationResponse
tokenResponse: (nullable OIDTokenResponse *)  tokenResponse
registrationResponse: (nullable OIDRegistrationResponse *)  NS_DESIGNATED_INITIALIZER 

Creates an auth state from an authorization, token and registration response.

Parameters
authorizationResponseThe authorization response.
tokenResponseThe token response.
registrationResponseThe registration response.

◆ initWithRegistrationResponse:()

- (instancetype) initWithRegistrationResponse: (OIDRegistrationResponse *)  registrationResponse

Creates an auth state from an registration response.

Parameters
registrationResponseThe registration response.

◆ performActionWithFreshTokens:()

- (void) performActionWithFreshTokens: (OIDAuthStateAction action

Calls the block with a valid access token (refreshing it first, if needed), or if a refresh was needed and failed, with the error that caused it to fail.

Parameters
actionThe block to execute with a fresh token. This block will be executed on the main thread.

◆ performActionWithFreshTokens:additionalRefreshParameters:()

- (void) performActionWithFreshTokens: (OIDAuthStateAction action
additionalRefreshParameters: (nullable NSDictionary< NSString *, NSString * > *)  additionalParameters 

Calls the block with a valid access token (refreshing it first, if needed), or if a refresh was needed and failed, with the error that caused it to fail.

Parameters
actionThe block to execute with a fresh token. This block will be executed on the main thread.
additionalParametersAdditional parameters for the token request if token is refreshed.

◆ performActionWithFreshTokens:additionalRefreshParameters:dispatchQueue:()

- (void) performActionWithFreshTokens: (OIDAuthStateAction action
additionalRefreshParameters: (nullable NSDictionary< NSString *, NSString * > *)  additionalParameters
dispatchQueue: (dispatch_queue_t)  dispatchQueue 

Calls the block with a valid access token (refreshing it first, if needed), or if a refresh was needed and failed, with the error that caused it to fail.

Parameters
actionThe block to execute with a fresh token. This block will be executed on the main thread.
additionalParametersAdditional parameters for the token request if token is refreshed.
dispatchQueueThe dispatchQueue on which to dispatch the action block.

◆ tokenRefreshRequest()

- (nullable OIDTokenRequest *) tokenRefreshRequest

Creates a token request suitable for refreshing an access token.

Returns
A OIDTokenRequest suitable for using a refresh token to obtain a new access token. @discussion After performing the refresh, call updateWithTokenResponse:error: to update the authorization state based on the response. Rather than doing the token refresh yourself, you should use performActionWithFreshTokens:.
See also
https://tools.ietf.org/html/rfc6749#section-1.5

◆ tokenRefreshRequestWithAdditionalParameters:()

- (nullable OIDTokenRequest *) tokenRefreshRequestWithAdditionalParameters: (nullable NSDictionary< NSString *, NSString * > *)  additionalParameters

Creates a token request suitable for refreshing an access token.

Parameters
additionalParametersAdditional parameters for the token request.
Returns
A OIDTokenRequest suitable for using a refresh token to obtain a new access token. @discussion After performing the refresh, call updateWithTokenResponse:error: to update the authorization state based on the response. Rather than doing the token refresh yourself, you should use performActionWithFreshTokens:.
See also
https://tools.ietf.org/html/rfc6749#section-1.5

◆ updateWithAuthorizationError:()

- (void) updateWithAuthorizationError: (NSError *)  authorizationError

Updates the authorization state based on an authorization error.

Parameters
authorizationErrorThe authorization error. @discussion Call this method if you receive an authorization error during an API call to invalidate the authentication state of this OIDAuthState. Don't call with errors unrelated to authorization, such as transient network errors. The authState:didEncounterAuthorizationError: (OIDAuthStateErrorDelegate-p) method of errorDelegate will be called with the error. You may optionally use the convenience method resourceServerAuthorizationErrorWithCode:errorResponse:underlyingError: (OIDErrorUtilities) to create NSError objects for use here. The latest error received is stored in authorizationError. Note: that after unarchiving this object, the NSError.userInfo property of this error will be nil.

◆ updateWithAuthorizationResponse:error:()

- (void) updateWithAuthorizationResponse: (nullable OIDAuthorizationResponse *)  authorizationResponse
error: (nullable NSError *)  error 

Updates the authorization state based on a new authorization response.

Parameters
authorizationResponseThe new authorization response to update the state with.
errorAny error encountered when performing the authorization request. Errors in the domain OIDOAuthAuthorizationErrorDomain are reflected in the auth state, other errors are assumed to be transient, and ignored. @discussion Typically called with the response from an incremental authorization request, or if using the implicit flow. Will clear the lastTokenResponse property.

◆ updateWithRegistrationResponse:()

- (void) updateWithRegistrationResponse: (nullable OIDRegistrationResponse *)  registrationResponse

Updates the authorization state based on a new registration response.

Parameters
registrationResponseThe new registration response to update the state with. @discussion Typically called with the response from a successful client registration request. Will reset the auth state.

◆ updateWithTokenResponse:error:()

- (void) updateWithTokenResponse: (nullable OIDTokenResponse *)  tokenResponse
error: (nullable NSError *)  error 

Updates the authorization state based on a new token response.

Parameters
tokenResponseThe new token response to update the state from.
errorAny error encountered when performing the authorization request. Errors in the domain OIDOAuthTokenErrorDomain are reflected in the auth state, other errors are assumed to be transient, and ignored. @discussion Typically called with the response from an authorization code exchange, or a token refresh.

Property Documentation

◆ refreshToken

- (NSString*) refreshToken
readnonatomicassign

The most recent refresh token received from the server. @discussion Rather than using this property directly, you should call performActionWithFreshTokens:.

Remarks
refresh_token
See also
https://tools.ietf.org/html/rfc6749#section-5.1

◆ scope

- (NSString*) scope
readnonatomicassign

The scope of the current authorization grant. @discussion This represents the latest scope returned by the server and may be a subset of the scope that was initially granted.

Remarks
scope

The documentation for this class was generated from the following file: