Support OAuth in your SDK app


To support OAuth in your SDK app, you must:

  • Handle the authorization and authentication using:

    • Server-to-server OAuth or
    • Proof Key for Code Exchange (PKCE) OAuth
  • Then you must handle the redirect from the user's browser to your native app using a Custom URL Scheme.

The sections below describe how to do this, using the iOS SDK sample app as an example. See Create an SDK App for details on how to create an SDK app. To follow along, download the iOS SDK sample app MobileRTCSample from the Marketplace, then see Zoom Meeting iOS SDK Getting started.

Server-to-server OAuth

The sequence diagram and steps below show an example of a server-to-server OAuth integration with Zoom.

  1. You must have a backend server to use server-to-server OAuth. See our sample application https://github.com/zoom/zoom-oauth-sample-app for an example of this. See the steps below as well. Your backend server must handle the following logic:
    1. An endpoint to check whether there is an access token that is valid for the user. If the access token does not exist, ask the user to perform OAuth authorization.
    2. An endpoint to use the access token to retrieve the Zoom Access Key (ZAK) from the Zoom API.
    3. Redirection back to your SDK application.
  2. Open MobileRTCSample (Sample app included in the iOS SDK), navigate to the Target > Info > URL Types, and add a name to the URL Schemes. This will be your custom URL scheme. Your backend must redirect to this URL scheme.
  1. Create a custom function in your SDK app, send a GET request to your backend endpoint to see if OAuth is needed. If the user's access token is still valid, make a call to the Zoom API instead to retrieve a ZAK token (Get user's ZAK. Otherwise, use the default browser to open the OAuth link (the testable Url).
  2. The auth link will redirect the user to login on zoom.us. Upon successful login, Marketplace presents the information and scope of the OAuth app and asks for authorization. Once the user provides consent, the Zoom server returns an authorization code to your backend server.
  3. Send the authorization code to the Zoom server to exchange for an access token.
  4. Use the access token to send a GET request to the Zoom Restful API https://api.zoom.us/v2/users/{'{'}userId}/zak to retrieve the ZAK, and to send a POST request to https://api.zoom.us/v2/users/{'{'}userId}/meeting to schedule a meeting.
  5. Redirect and launch the SDK application from your backend server and invoke your SDK app with a custom URL scheme. For iOS apps, the following callback will be triggered:
-(BOOL)application:(UIApplication *)app openURL: (NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
  1. With the ZAK and meeting number, call the start or join meeting interfaces to start/join a meeting. If you would like to start an instant meeting, please use your OAuth backend server to call https://api.zoom.us/v2/users/{'{'}userId}/meeting to create a meeting first.

Proof key for code exchange (PKCE) OAuth

Proof key for code exchange, or PKCE, is a special type of OAuth authorization that does not require a backend server. The client application directly communicates with Zoom servers to complete the OAuth process. See the sequence diagram and steps below for details.

  1. In your OAuth application on Marketplace, put the custom URL scheme in the redirect URL and allow list.
  2. Open MobileRTCSample (Sample app included in the iOS SDK), navigate to the Target > Info > URL Types, and add a name to the URL Schemes. This will be your custom URL scheme.
  1. Generate a code challenge based on the code verifier. For example, using Objective-C on iOS:
#define ENTROPY_SOURCE_LENGTH 32
NSMutableData *entropySource = [NSMutableData dataWithLength:ENTROPY_SOURCE_LENGTH];
int result = SecRandomCopyBytes(kSecRandomDefault, entropySource.length, entropySource.mutableBytes);
// If the SecRandomCopyBytes did not succeed, terminate the OAuth process and try again later.
if (result != errSecSuccess) {
return;
}
NSString *verifier = [[[[entropySource base64EncodedStringWithOptions:0]
stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];
// Using CommonCrypto to create challenge.
u_int8_t buffer[CC_SHA256_DIGEST_LENGTH * sizeof(u_int8_t)];
memset(buffer, 0x0, CC_SHA256_DIGEST_LENGTH);
NSData *data = [verifier dataUsingEncoding:NSUTF8StringEncoding];
CC_SHA256([data bytes], (CC_LONG)[data length], buffer);
NSData *hash = [NSData dataWithBytes:buffer length:CC_SHA256_DIGEST_LENGTH];
// Please note that currently the code challenge does not support Base64 URL encoding.
NSMutableString *challenge = [NSMutableString string];
[hash enumerateByteRangesUsingBlock:^(const void *bytes, NSRange byteRange, BOOL *stop) {
for (NSUInteger i = 0; i < byteRange.length; ++i) {
[challenge appendFormat:@"%02x", ((uint8_t*)bytes)[i]];
}
}];

Note: Currently the code challenge does not support Base64 URL encoding. Do not encode your code challenge or the code challenge verification would fail.

  1. Include the code challenge as a parameter in the authorization URL and use the default browser to open the auth link. For example:
// Compose the URL query item.
NSURLQueryItem *clientIdItem = [NSURLQueryItem queryItemWithName:@"client_id" value:kOAuthClientId];
NSURLQueryItem *responseTypeItem = [NSURLQueryItem queryItemWithName:@"response_type" value:@"code"];
NSURLQueryItem *redirectUriItem = [NSURLQueryItem queryItemWithName:@"redirect_uri" value:redirectURL];
NSURLQueryItem *codeChallengeItem = [NSURLQueryItem queryItemWithName:@"code_challenge" value:challenge];
NSURLQueryItem *codeChallengeMethodItem = [NSURLQueryItem queryItemWithName:@"code_challenge_method" value:@"S256"];
// Compose auth URL.
NSURLComponents *authURLComponents = [[NSURLComponents alloc] init];
authURLComponents.scheme = @"https";
authURLComponents.host = @"zoom.us";
authURLComponents.path = @"/oauth/authorize";
authURLComponents.queryItems = @[ clientIdItem, responseTypeItem, redirectUriItem, codeChallengeItem, codeChallengeMethodItem ];
[[UIApplication sharedApplication] openURL:authURLComponents.URL];
  1. The auth link redirects the user to login on zoom.us. Upon successful login, Marketplace presents the information and scope of the OAuth app and asks for authorization. Once the user provides consent, the Zoom server calls your redirect URL, which contains the custom URL scheme to trigger your app, and provides an authorization code. For an iOS app, the following callback in AppDelegate.m will be triggered:
-(BOOL)application:(UIApplication *)app openURL: (NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options

Make sure the redirect URL contains the authorization code:

NSURLComponents *urlComponents = [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO];
for (NSURLQueryItem *item in urlComponents.queryItems) {
if([item.name isEqualToString:@"code"]) {
code = [NSString stringWithString:item.value];
[[[SDKStartJoinMeetingPresenter alloc] init] retrieveAccessToken:code];
}
}
  1. Parse out the authorization code, send a request with the authorization code and the code verifier to the Zoom server to exchange for an access token.
NSString *accessEndPoint = @"https://zoom.us/oauth/token";
NSString *redirectURL = @"[Your redirect URL with custom URI scheme]";
// Retrieve code verifier from local storage
NSString *verifier = [[NSUserDefaults standardUserDefaults] stringForKey:@"codeVerifier"];
NSURL *url = [NSURL URLWithString:accessEndPoint];
NSData *postData =[[NSString stringWithFormat:@"code=%@&grant_type=authorization_code&redirect_uri=%@&code_verifier=%@",code, redirectURL,verifier] dataUsingEncoding:NSUTF8StringEncoding];
NSString *authCode = [self encodeStringWithBase64:[NSString stringWithFormat:@"%@:%@",kOAuthClientId,kOAuthClientSecret]];
// Make a POST request to retrieve the access token.
NSMutableURLRequest *mRequest = [NSMutableURLRequest requestWithURL:url cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval:60];
[mRequest setHTTPMethod:@"POST"];
[mRequest setHTTPBody:postData];
[mRequest setValue:[NSString stringWithFormat:@"Basic %@",authCode] forHTTPHeaderField:@"Authorization"];
[mRequest setValue:@"application/x-www-form-urlencoded" forHTTPHeaderField:@"Content-Type"];
NSData *resultData = [NSURLConnection sendSynchronousRequest:mRequest returningResponse:nil error:nil];
NSDictionary *result = [NSJSONSerialization JSONObjectWithData:resultData options:NSJSONReadingAllowFragments error:nil];
NSString *accessToken = [result objectForKey:@"access_token"];
if (accessToken != nil) {
[self retrieveUserInfo:accessToken];
}
  1. Use the access token to call the Zoom RESTful API: https://api.zoom.us/v2/users/{'{'}userId}/zak to retrieve the ZAK.
NSString* zakURL = @"https://api.zoom.us/v2/users/me/zak";
// Retrieve ZAK
NSMutableURLRequest *zakRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:zakURL] cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval:60];
[zakRequest setHTTPMethod:@"GET"];
[zakRequest setValue:[NSString stringWithFormat:@"Bearer %@",accessToken] forHTTPHeaderField:@"Authorization"];
[zakRequest setValue:@"application/x-www-form-urlencoded" forHTTPHeaderField:@"Content-Type"];
NSData *zakData = [NSURLConnection sendSynchronousRequest:zakRequest returningResponse:nil error:nil];
NSDictionary *zakResult = [NSJSONSerialization JSONObjectWithData:zakData options:NSJSONReadingAllowFragments error:nil];
NSString *zak = [zakResult objectForKey:@"token"];
if (zak != nil) {
// Join a meeting
}
  1. With the ZAK and meeting number, call the start or join meeting interfaces to start/join a meeting.

Custom URL scheme

To complete the OAuth process on your native app, you must have a custom URL scheme. The sections below include the methods of how to register custom URL schemes on each platform. You can find out more in IETF rfc8252: OAuth 2.0 for Native Apps.

iOS and macOS

You can register the URL scheme in the same way for iOS and macOS as they both use Xcode. Navigate to the Target > Info > URL Types, and add a name to the URL Schemes. This will be your custom URL scheme. Your backend must redirect to this URL scheme. See the screenshot below for details.

Android

To register the custom URL scheme to trigger your Android application, simply add the following intent-filter to the activity that you would like to invoke in the AndroidManifest.xml:

<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:scheme="com.example.app"
/>
</intent-filter>

The intent filter allows you to trigger your app with the URL com.example.app//

Windows

To register for the Custom URL Scheme on Windows OS, you must edit the Registry Editor:

  1. Create a new text document with Notepad.
  2. Insert the following code:
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\urlscheme]
"URL Protocol"="<PATH TO YOUR APP's EXE file>"
@="YOURCUSTOMProtocol"
[HKEY_CLASSES_ROOT\urlscheme\DefaultIcon]
@="<PATH TO YOUR APP's EXE file>,1"
[HKEY_CLASSES_ROOT\urlscheme\shell]
[HKEY_CLASSES_ROOT\urlscheme\shell\open]
[HKEY_CLASSES_ROOT\urlscheme\shell\open\command]
@="\"<PATH TO YOUR APP's EXE file>" \"%1\""
  1. Save the file and change the extension to “.reg”.
  2. Double click on the .reg file to register your Custom URL Scheme.

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.