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

OIDAuthorizationResponse *	lastAuthorizationResponse
	The most recent authorization response used to update the authorization state. For the implicit flow, this will contain the latest access token.

OIDTokenResponse *	lastTokenResponse
	The most recent token response used to update this authorization state. This will contain the latest access token.

OIDRegistrationResponse *	lastRegistrationResponse
	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< OIDAuthStateChangeDelegate >	stateChangeDelegate
	The `OIDAuthStateChangeDelegate` delegate. @discussion Use the delegate to observe state changes (and update storage) as well as error states.

id< OIDAuthStateErrorDelegate >	errorDelegate
	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

authorizationRequest	The authorization request to present.
externalUserAgent	A external user agent that can present an external user-agent request.
callback	The 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

authorizationRequest	The authorization request to present.
presentingViewController	The view controller from which to present the `SFSafariViewController`. On iOS 13, the window of this UIViewController is used as the ASPresentationAnchor.
callback	The 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

authorizationResponse The authorization response.

◆ initWithAuthorizationResponse:tokenResponse:()

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

Creates an auth state from an authorization and token response.

Parameters

authorizationResponse	The authorization response.
tokenResponse	The 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

authorizationResponse	The authorization response.
tokenResponse	The token response.
registrationResponse	The registration response.

◆ initWithRegistrationResponse:()

- (instancetype) initWithRegistrationResponse: (OIDRegistrationResponse *) registrationResponse

Creates an auth state from an registration response.

Parameters

registrationResponse The 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

action The 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

action	The block to execute with a fresh token. This block will be executed on the main thread.
additionalParameters	Additional 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

action	The block to execute with a fresh token. This block will be executed on the main thread.
additionalParameters	Additional parameters for the token request if token is refreshed.
dispatchQueue	The 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

additionalParameters Additional 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

authorizationError The 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

authorizationResponse	The new authorization response to update the state with.
error	Any 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

registrationResponse The 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

tokenResponse	The new token response to update the state from.
error	Any 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:

Source/OIDAuthState.h

Instance Methods

Class Methods

Properties

Detailed Description

Method Documentation

◆ authStateByPresentingAuthorizationRequest:externalUserAgent:callback:()

◆ authStateByPresentingAuthorizationRequest:presentingViewController:callback:()

◆ initWithAuthorizationResponse:()

◆ initWithAuthorizationResponse:tokenResponse:()

◆ initWithAuthorizationResponse:tokenResponse:registrationResponse:()

◆ initWithRegistrationResponse:()

◆ performActionWithFreshTokens:()

◆ performActionWithFreshTokens:additionalRefreshParameters:()

◆ performActionWithFreshTokens:additionalRefreshParameters:dispatchQueue:()

◆ tokenRefreshRequest()

◆ tokenRefreshRequestWithAdditionalParameters:()

◆ updateWithAuthorizationError:()

◆ updateWithAuthorizationResponse:error:()

◆ updateWithRegistrationResponse:()

◆ updateWithTokenResponse:error:()

Property Documentation

◆ refreshToken

◆ scope