OAuth2Base

open class OAuth2Base: OAuth2Securable

Class extending on OAuth2Requestable, exposing configuration and maintaining context, serving as base class for OAuth2.

  • The grant type represented by the class, e.g. authorization_code for code grants.

    Declaration

    Swift

    open class var grantType: String

  • The response type expected from an authorize call, e.g. code for code grants.

    Declaration

    Swift

    open class var responseType: String?

  • Settings related to the client-server relationship.

    Declaration

    Swift

    open let clientConfig: OAuth2ClientConfig

  • Client-side authorization options.

    Declaration

    Swift

    open var authConfig = OAuth2AuthConfig()

  • The client id.

    Declaration

    Swift

    public final var clientId: String?

  • The client secret, usually only needed for code grant.

    Declaration

    Swift

    public final var clientSecret: String?

  • The name of the client, as used during dynamic client registration. Use client_name during initalization to set.

    Declaration

    Swift

    open var clientName: String?

  • The URL to authorize against.

    Declaration

    Swift

    public final var authURL: URL

  • The URL string where we can exchange a code for a token; if nil authURL will be used.

    Declaration

    Swift

    public final var tokenURL: URL?

  • The scope currently in use.

    Declaration

    Swift

    public final var scope: String?

  • The redirect URL string to use.

    Declaration

    Swift

    public final var redirect: String?

  • Context for the current auth dance.

    Declaration

    Swift

    open var context = OAuth2ContextStore()

  • The receiver’s access token.

    Declaration

    Swift

    open var accessToken: String?

  • The receiver’s id token.

    Declaration

    Swift

    open var idToken: String?

  • The access token’s expiry date.

    Declaration

    Swift

    open var accessTokenExpiry: Date?

  • The receiver’s long-time refresh token.

    Declaration

    Swift

    open var refreshToken: String?

  • Custom or overridden HTML headers to be used during authorization.

    Declaration

    Swift

    public var authHeaders: OAuth2Headers?

  • Custom authorization parameters.

    Declaration

    Swift

    public var authParameters: OAuth2StringDict?

  • This closure is internally used with authorize(params:callback:) and only exposed for subclassing reason, do not mess with it!

    Declaration

    Swift

    public final var didAuthorizeOrFail: ((_ parameters: OAuth2JSON?, _ error: OAuth2Error?) -> Void)?

  • Returns true if the receiver is currently authorizing.

    Declaration

    Swift

    public final var isAuthorizing: Bool

  • Closure called after the regular authorization callback, on the main thread. You can use this callback when you’re performing authorization manually and/or for cleanup operations.

    Declaration

    Swift

    public final var afterAuthorizeOrFail: ((_ authParameters: OAuth2JSON?, _ error: OAuth2Error?) -> Void)?

    Parameters

    authParameters

    All authorization parameters; non-nil (but possibly empty) on success, nil on error
    error

    OAuth2Error giving the failure reason; if nil and authParameters is also nil, the process was aborted.

  • For internal use, don’t mess with it, it’s public only for subclassing and compilation reasons. Executed right before afterAuthorizeOrFail.

    Declaration

    Swift

    public final var internalAfterAuthorizeOrFail: ((_ wasFailure: Bool, _ error: OAuth2Error?) -> Void)?

  • Designated initializer.

    The following settings keys are currently supported:

    • client_id (String)
    • client_secret (String), usually only needed for code grant
    • authorize_uri (URL-String)
    • token_uri (URL-String), if omitted the authorize_uri will be used to obtain tokens
    • redirect_uris (Array of URL-Strings)

    • scope (String)

    • client_name (String)

    • registration_uri (URL-String)

    • logo_uri (URL-String)

    • keychain (Bool, true by default, applies to using the system keychain)

    • keychain_access_mode (String, value for keychain kSecAttrAccessible attribute, kSecAttrAccessibleWhenUnlocked by default)

    • keychain_access_group (String, value for keychain kSecAttrAccessGroup attribute, nil by default)

    • keychain_account_for_client_credentials(String, clientCredentials by default)

    • keychain_account_for_tokens(String, currentTokens by default)

    • secret_in_body (Bool, false by default, forces the flow to use the request body for the client secret)

    • token_assume_unexpired (Bool, true by default, whether to use access tokens that do not come with an expires_in parameter)

    • verbose (Bool, false by default, applies to client logging)

    Declaration

    Swift

    override public init(settings: OAuth2JSON)

Keychain Integration

  • Overrides base implementation to return the authorize URL.

    Declaration

    Swift

    override open func keychainServiceName() -> String

  • Overrides base implementation to return the authorize URL.

    Declaration

    Swift

    override open func storableCredentialItems() -> [String: Any]?

    Return Value

    A dictionary with String keys and Any items

  • Overrides base implementation to return the authorize URL.

    Declaration

    Swift

    override open func storableTokenItems() -> [String: Any]?

    Return Value

    A dictionary with String keys and Any items

  • Overrides base implementation to return the authorize URL.

    Declaration

    Swift

    override open func forgetClient()

  • Overrides base implementation to return the authorize URL.

    Declaration

    Swift

    override open func forgetTokens()

Request Signing

  • Return an OAuth2Request, a NSMutableURLRequest subclass, that has already been signed and can be used against your OAuth2 endpoint.

    This method by default ignores locally cached data and specifies a timeout interval of 20 seconds. This should be ideal for small JSON data requests, but you probably don’t want to disable cache for binary data like avatars.

    Declaration

    Swift

    open func request(forURL url: URL, cachePolicy: NSURLRequest.CachePolicy = .reloadIgnoringLocalCacheData) -> URLRequest

    Parameters

    forURL

    The URL to create a request for
    cachePolicy

    The cache policy to use, defaults to NSURLRequestCachePolicy.ReloadIgnoringLocalCacheData

    Return Value

    OAuth2Request for the given URL

Callbacks

  • Subclasses override this method to extract information from the supplied redirect URL.

    Declaration

    Swift

    open func handleRedirectURL(_ redirect: URL) throws

    Parameters

    redirect

    The redirect URL returned by the server that you want to handle

  • Internally used on success, calls the callbacks on the main thread.

    This method is only made public in case you want to create a subclass and call didAuthorize(parameters:) at an override point. If you call this method yourself on your OAuth2 instance you might screw things up badly.

    Declaration

    Swift

    public final func didAuthorize(withParameters parameters: OAuth2JSON)

    Parameters

    withParameters

    The parameters received during authorization

  • Internally used on error, calls the callbacks on the main thread with the appropriate error message.

    This method is only made public in case you want to create a subclass and need to call didFail(error:) at an override point. If you call this method yourself on your OAuth2 instance you might screw things up royally.

    Declaration

    Swift

    public final func didFail(with error: OAuth2Error?)

    Parameters

    error

    The error that led to authorization failure; will use .requestCancelled on the callbacks if nil is passed

  • Allows to abort authorization currently in progress.

    Declaration

    Swift

    open func abortAuthorization()

Response Parsing

  • Handles access token error response.

    Declaration

    Swift

    open func assureNoErrorInResponse(_ params: OAuth2JSON, fallback: String? = nil) throws

    Parameters

    params

    The URL parameters returned from the server
    fallback

    The message string to use in case no error description is found in the parameters

    Return Value

    An OAuth2Error

  • Parse response data returned while exchanging the code for a token.

    This method expects token data to be JSON, decodes JSON and fills the receiver’s properties accordingly. If the response contains an error key, will parse the error and throw it.

    Declaration

    Swift

    open func parseAccessTokenResponse(data: Data) throws -> OAuth2JSON

    Parameters

    data

    NSData returned from the call

    Return Value

    An OAuth2JSON instance with token data; may contain additional information

  • Parse response data returned while exchanging the code for a token.

    This method extracts token data and fills the receiver’s properties accordingly. If the response contains an error key, will parse the error and throw it. The method is final to ensure correct order of error parsing and not parsing the response if an error happens. This is not possible in overrides. Instead, override the various assureXy(dict:) methods, especially assureAccessTokenParamsAreValid().

    Declaration

    Swift

    public final func parseAccessTokenResponse(params: OAuth2JSON) throws -> OAuth2JSON

    Parameters

    params

    Dictionary data parsed from the response

    Return Value

    An OAuth2JSON instance with token data; may contain additional information

  • This method does nothing, but allows subclasses to fix parameter names before passing the access token response to OAuth2ClientConfigs updateFromResponse().

    Declaration

    Swift

    open func normalizeAccessTokenResponseKeys(_ dict: OAuth2JSON) -> OAuth2JSON

    Parameters

    dict

    The dictionary that was returned from an access token response

    Return Value

    The dictionary with fixed key names

  • Parse response data returned while using a refresh token.

    This method extracts token data, expected to be JSON, and fills the receiver’s properties accordingly. If the response contains an error key, will parse the error and throw it.

    Declaration

    Swift

    open func parseRefreshTokenResponseData(_ data: Data) throws -> OAuth2JSON

    Parameters

    data

    NSData returned from the call

    Return Value

    An OAuth2JSON instance with token data; may contain additional information

  • This method does nothing, but allows subclasses to fix parameter names before passing the refresh token response to OAuth2ClientConfigs updateFromResponse().

    Declaration

    Swift

    open func normalizeRefreshTokenResponseKeys(_ dict: OAuth2JSON) -> OAuth2JSON

    Parameters

    dict

    The dictionary that was returned from a refresh token response

    Return Value

    The dictionary with fixed key names

  • This method checks state, throws OAuth2Error.missingState or OAuth2Error.invalidState. Resets state if it matches.

    Declaration

    Swift

    public final func assureMatchesState(_ params: OAuth2JSON) throws

  • Throws unless token_type is bearer (case-insensitive).

    Declaration

    Swift

    open func assureCorrectBearerType(_ params: OAuth2JSON) throws

  • Called when parsing the access token response. Does nothing by default, implicit grant flows check state.

    Declaration

    Swift

    open func assureAccessTokenParamsAreValid(_ params: OAuth2JSON) throws

  • Called when parsing the refresh token response. Does nothing by default.

    Declaration

    Swift

    open func assureRefreshTokenParamsAreValid(_ params: OAuth2JSON) throws