1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
/*! @file GTMAppAuthFetcherAuthorization.h
@brief GTMAppAuth SDK
@copyright
Copyright 2016 Google Inc.
@copydetails
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
#ifndef GTMAPPAUTH_USER_IMPORTS
#import <GTMSessionFetcher/GTMSessionFetcher.h>
#else // GTMAPPAUTH_USER_IMPORTS
#import "GTMSessionFetcher.h"
#endif // GTMAPPAUTH_USER_IMPORTS
@class OIDAuthState;
@class OIDServiceConfiguration;
NS_ASSUME_NONNULL_BEGIN
/*! @brief The userInfo key for the @c NSURLRequest.
*/
extern NSString *const GTMAppAuthFetcherAuthorizationErrorRequestKey;
/*! @brief The error domain for errors specific to the session fetcher authorization.
*/
extern NSString *const GTMAppAuthFetcherAuthorizationErrorDomain;
/*! @brief Enum of all possible error codes in the @c ::GTMAppAuthFetcherAuthorizationErrorDomain
domain.
@discussion Note that these are GTMAppAuth-specific errors. When AppAuth errors are encountered,
those are returned instead.
*/
typedef NS_ENUM(NSInteger, GTMAppAuthFetcherAuthorizationError) {
GTMAppAuthFetcherAuthorizationErrorUnauthorizableRequest = -1004
};
typedef void (^GTMAppAuthFetcherAuthorizationCompletion)(NSError *_Nullable error);
@class GTMAppAuthFetcherAuthorization;
/*! @protocol GTMAppAuthFetcherAuthorizationTokenRefreshDelegate
@brief Delegate of the GTMAppAuthFetcherAuthorization used to supply additional parameters on
token refresh.
*/
@protocol GTMAppAuthFetcherAuthorizationTokenRefreshDelegate <NSObject>
/*! @brief Called before a token refresh request is performed.
@param authorization The @c GTMFetcherAuthorization performing the token refresh.
@return A dictionary of parameters to be added to the token refresh request.
*/
- (nullable NSDictionary<NSString *, NSString *> *)additionalRefreshParameters:
(GTMAppAuthFetcherAuthorization *)authorization;
@end
/*! @brief An implementation of the @c GTMFetcherAuthorizationProtocol protocol for the AppAuth
library.
@discussion Enables you to use AppAuth with the GTM Session Fetcher library.
*/
@interface GTMAppAuthFetcherAuthorization : NSObject <GTMFetcherAuthorizationProtocol,
NSSecureCoding>
/*! @brief The AppAuth authentication state.
*/
@property(nonatomic, readonly) OIDAuthState *authState;
/*! @brief Service identifier, for example "Google"; not used for authentication.
@discussion The provider name is just for allowing stored authorization to be associated
with the authorizing service.
*/
@property(nullable, nonatomic, readonly) NSString *serviceProvider;
/*! @brief User ID from the ID Token.
* @discussion Note: Never send this value to your backend as an authentication token, rather send
* an ID Token and validate it.
*/
@property(nullable, nonatomic, readonly) NSString *userID;
/*! @brief Email verified status; not used for authentication.
@discussion The verified string can be checked with -boolValue. If the result is false, then
the email address is listed with the account on the server, but the address has not been
confirmed as belonging to the owner of the account.
*/
@property(nullable, nonatomic, readonly) NSString *userEmailIsVerified;
@property(nullable, nonatomic, weak) id<GTMAppAuthFetcherAuthorizationTokenRefreshDelegate>
tokenRefreshDelegate;
/*! @brief Creates a new @c GTMAppAuthFetcherAuthorization using the given @c OIDAuthState from
AppAuth.
@param authState The authorization state.
*/
- (instancetype)initWithAuthState:(OIDAuthState *)authState;
/*! @brief Creates a new @c GTMAppAuthFetcherAuthorization using the given @c OIDAuthState from
AppAuth.
@param authState The authorization state.
@param serviceProvider An optional string to describe the service.
@param userID An optional string of the user ID.
@param userEmail An optional string of the user's email address.
@param userEmailIsVerified An optional string representation of a boolean to indicate that the
email address has been verified. Pass @"true" for @c YES, or @"false" for @c NO.
@discussion Designated initializer.
*/
- (instancetype)initWithAuthState:(OIDAuthState *)authState
serviceProvider:(nullable NSString *)serviceProvider
userID:(nullable NSString *)userID
userEmail:(nullable NSString *)userEmail
userEmailIsVerified:(nullable NSString *)userEmailIsVerified
NS_DESIGNATED_INITIALIZER;
#if !GTM_APPAUTH_SKIP_GOOGLE_SUPPORT
/*! @brief Convenience method to return an @c OIDServiceConfiguration for Google.
@return A @c OIDServiceConfiguration object setup with Google OAuth endpoints.
*/
+ (OIDServiceConfiguration *)configurationForGoogle;
#endif // !GTM_APPAUTH_SKIP_GOOGLE_SUPPORT
/*! @brief Adds an authorization header to the given request, using the authorization state.
Refreshes the access token if needed.
@param request The request to authorize.
@param handler The block that is called after authorizing the request is attempted. If @c error
is non-nil, the authorization failed. Errors in the domain @c ::OIDOAuthTokenErrorDomain
indicate that the authorization itself is invalid, and will need to be re-obtained from the
user. Errors in the @c GTMAppAuthFetcherAuthorizationErrorDomain indicate another
unrecoverable errors. Errors in other domains may indicate a transitive error condition such
as a network error, and typically you do not need to reauthenticate the user on such errors.
@discussion The completion handler is scheduled on the main thread, unless the @c callbackQueue
property is set on the @c fetcherService in which case the handler is scheduled on that
queue.
*/
- (void)authorizeRequest:(nullable NSMutableURLRequest *)request
completionHandler:(GTMAppAuthFetcherAuthorizationCompletion)handler;
/*! @brief Returns YES if the authorization state is currently valid.
@discussion Note that this doesn't guarantee that a request will get a valid authorization, as
the authorization state could become invalid on on the next token refresh.
*/
- (BOOL)canAuthorize;
@end
NS_ASSUME_NONNULL_END
|
