Gmail IMAP: Workspace Domain-Wide Delegation
See more GMail SMTP/IMAP/POP Examples
Use a JSON service-account key to impersonate a Workspace user for IMAP with https://www.googleapis.com/auth/gmail.imap_admin. A Workspace administrator must authorize the service account's numeric OAuth client ID for this exact scope in domain-wide delegation. The impersonated user must have an active Gmail mailbox.
This IMAP-only scope reveals labels hidden by Show in IMAP and messages excluded by the user's folder-size limit. It does not authorize SMTP or POP and is not available for personal Gmail accounts or ordinary user-consent flows. Workspace administrative access policies still apply.
Protect the private key and limit who can execute the delegated application. The signed JWT exchange produces a short-lived token without a refresh token; obtain another when necessary and reconnect. Keep the computer clock accurate. This example lists folders and examines INBOX read-only without printing credentials.
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://www.googleapis.com/auth/gmail.imap_admin";
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;
}
// With gmail.imap_admin, labels hidden by the user's Show in IMAP setting are included.
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];