Gmail IMAP: Workspace Service Account with a JSON Key
Use a service-account JSON key with Google Workspace domain-wide delegation. A Workspace administrator must authorize the service account's numeric OAuth client ID for https://mail.google.com/. Set SubEmailAddress to the Workspace user whose active Gmail mailbox is being accessed, and use that same address for IMAP login.
A service account has no Gmail mailbox of its own; leaving the impersonated user empty does not grant access to a personal Gmail account. The signed JWT exchange yields a short-lived token without a refresh token. Obtain another when needed, protect the private key, and keep the computer clock accurate.
This example lists visible folders and examines INBOX read-only. For the different visibility rules of the IMAP-only administrative scope, see gmail.imap_admin delegation.
See the Gmail SMTP, IMAP, and POP3 guide for current authentication choices and Gmail-specific examples.
Chilkat Objective-C Downloads
#import <NSString.h>
#import <CkoJsonObject.h>
#import <CkoAuthGoogle.h>
#import <CkoSocket.h>
#import <CkoImap.h>
#import <CkoMailboxes.h>
BOOL success = NO;
// Assumes Chilkat is unlocked. See Global Unlock Sample.
NSString *mailbox = @"user@example.com";
CkoJsonObject *key = [[CkoJsonObject alloc] init];
success = [key LoadFile: @"gmail-service-account.json"];
if (success != YES) {
NSLog(@"%@",@"Could not load the private service-account key.");
return;
}
if (([key StringOfEquals: @"type" value: @"service_account" caseSensitive: YES] != YES) || ([[key JsonTypeOf: @"private_key"] intValue] != 1)) {
NSLog(@"%@",@"Expected a Google service-account JSON key.");
return;
}
CkoAuthGoogle *auth = [[CkoAuthGoogle alloc] init];
auth.JsonKey = [key Emit];
auth.SubEmailAddress = mailbox;
auth.Scope = @"https://mail.google.com/";
auth.ExpireNumSeconds = [NSNumber numberWithInt:3600];
CkoSocket *connection = [[CkoSocket alloc] init];
connection.RequireSslCertVerify = YES;
success = [connection Connect: @"www.googleapis.com" port: [NSNumber numberWithInt: 443] ssl: YES maxWaitMs: [NSNumber numberWithInt: 10000]];
if (success != YES) {
NSLog(@"%@",@"Could not establish the Google token connection.");
return;
}
success = [auth ObtainAccessToken: connection];
[connection Close: [NSNumber numberWithInt: 1000]];
if (success != YES) {
NSLog(@"%@",@"Check the key, domain-wide delegation client ID/scope, user, and computer clock.");
return;
}
CkoImap *imap = [[CkoImap alloc] init];
imap.Ssl = YES;
imap.Port = [NSNumber numberWithInt:993];
imap.RequireSslCertVerify = YES;
imap.AuthMethod = @"XOAUTH2";
success = [imap Connect: @"imap.gmail.com"];
if (success != YES) {
NSLog(@"%@",@"Could not establish the Gmail IMAP TLS connection.");
return;
}
success = [imap Login: mailbox password: auth.AccessToken];
if (success != YES) {
[imap Disconnect];
NSLog(@"%@",@"IMAP authentication failed. Check the mailbox, scope, expiry, and account policy.");
return;
}
CkoMailboxes *folders = [[CkoMailboxes alloc] init];
success = [imap MbxList: NO reference: @"" mbxPattern: @"*" mboxes: folders];
if (success != YES) {
[imap Logout];
[imap Disconnect];
NSLog(@"%@",@"Could not list Gmail folders.");
return;
}
// List the labels visible through ordinary full-mail IMAP access.
int i = 0;
while ((i < [folders.Count intValue])) {
NSLog(@"%@",[folders GetName: [NSNumber numberWithInt: i]]);
i = i + 1;
}
success = [imap ExamineMailbox: @"INBOX"];
if (success != YES) {
[imap Logout];
[imap Disconnect];
NSLog(@"%@",@"Could not examine the impersonated user's INBOX.");
return;
}
NSLog(@"%@%d",@"INBOX messages: ",[imap.NumMessages intValue]);
[imap Logout];
[imap Disconnect];