Object Storage Service:Authorize access by using OSS SDK for iOS

Usage notes

When you use the STS authentication mode or self-signed mode, make sure that the callback function that you use can return the security token and signature. If you must obtain the token and signature from the app server by sending a request in the callback function, we recommend that you call the synchronous API operations included in the network library. The callback function runs in the child thread of the request generated by the SDK and does not block the main thread.

STS authentication mode

To access OSS by using temporary access credentials provided by STS, perform the following operations:

1. Obtain temporary access credentials.

   Temporary access credentials include a security token and a temporary AccessKey pair. The temporary AccessKey pair consists of an AccessKey ID and an AccessKey secret. The validity period of temporary access credentials is in seconds. The minimum validity period of temporary access credentials is 900 seconds. The maximum validity period of temporary access credentials is the maximum session duration specified for the current role. For more information, see Specify the maximum session duration for a RAM role.

   You can use one of the following methods to obtain temporary access credentials:

   • Method 1:

     Call the AssumeRole operation to obtain temporary access credentials.

   • Method 2

     Use STS SDKs to obtain temporary access credentials. For more information, see STS SDK overview.

2. Use temporary access credentials to initialize OSS SDK for iOS.

   id<OSSCredentialProvider> credential = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:@"<StsToken.AccessKeyId>" secretKeyId:@"<StsToken.SecretKeyId>" securityToken:@"<StsToken.SecurityToken>"];
   client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential];

   Note

   To use OSSAuthCredentialProvider to initialize OSS SDK for iOS, see Initialization.

   When you initialize the SDK by using temporary access credentials, take note of the validity period of the security token. The following sample code provides an example on how to determine the validity period of an security token:

   NSDateFormatter * fm = [NSDateFormatter new];
   fm.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
   [fm setDateFormat:@"yyyy-MM-dd'T'HH:mm:ssZ"];
   NSDate *expirationDate = [fm dateFromString:@"<StsToken.Expiration>"];
   NSTimeInterval interval = [expirationDate timeIntervalSinceDate:[NSDate date]];
   // The security token is about to expire within less than five minutes. 
   if (interval < 5 * 60) {
       id<OSSCredentialProvider> credential = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:@"<StsToken.AccessKeyId>" secretKeyId:@"<StsToken.SecretKeyId>" securityToken:@"<StsToken.SecurityToken>"];
       client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential];
   }

   • Manually update the security token

     When the security token is about to expire, you can create a new OSSClient instance or update CredentialProvider by using the following method:

     id<OSSCredentialProvider> credential = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:@"<StsToken.AccessKeyId>" secretKeyId:@"<StsToken.SecretKeyId>" securityToken:@"<StsToken.SecurityToken>"];
     client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential];

   • Automatically update the security token

     If you want the SDK to automatically update the security token, you must configure a callback function in your app. The callback fuction obtains a federation token (security token) and returns the token to the SDK. The SDK uses the security token to generate signatures. When the security token needs to be updated, the SDK calls the callback function to obtain a new token.

     id<OSSCredentialProvider> credential = [[OSSFederationCredentialProvider alloc] initWithFederationTokenGetter:^OSSFederationToken * {
         // Obtain a federation token and return it in an OSSFederationToken object. 
         // If the federation token is not obtained, nil is returned. 
           OSSFederationToken * token;
         // Obtain a federation token from your server. 
         ...
         return token;
     }];
     client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential];

     Note

     If you obtain all fields that are required to generate an security token by using other methods, you can directly return the token in the callback. In this case, you must manually update the token, and then reconfigure OSSCredentialProvider of the OSSClient instance.

     If the URL of the server from which you request a token is http://localhost:8080/distribute-token.json, the following data is returned:

     {
         "StatusCode": 200,
         "AccessKeyId":"STS.iA645eTOXEqP3cg3****",
         "AccessKeySecret":"rV3VQrpFQ4BsyHSAvi5NVLpPIVffDJv4LojU****",
         "Expiration":"2015-11-03T09:52:59Z",
         "SecurityToken":"CAES7QIIARKAAZPlqaN9ILiQZPS+JDkS/GSZN45RLx4YS/p3OgaUC+oJl3XSlbJ7StKpQ****"
     }                           

     The following sample code provides an example on how to implement OSSFederationCredentialProvider:

     id<OSSCredentialProvider> credential2 = [[OSSFederationCredentialProvider alloc] initWithFederationTokenGetter:^OSSFederationToken * {
         // Create a request to access your service server. 
         NSURL * url = [NSURL URLWithString:@"http://localhost:8080/distribute-token.json"];
         // Use a request to set the parameters required by your server. 
         NSURLRequest * request = [NSURLRequest requestWithURL:url];
         OSSTaskCompletionSource * tcs = [OSSTaskCompletionSource taskCompletionSource];
         NSURLSession * session = [NSURLSession sharedSession];
         // Send the request. 
         NSURLSessionTask * sessionTask = [session dataTaskWithRequest:request
                                                     completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                         if (error) {
                                                             [tcs setError:error];
                                                             return;
                                                         }
                                                         [tcs setResult:data];
                                                     }];
         [sessionTask resume];
         // Wait until the response to the request is returned. 
         [tcs.task waitUntilFinished];
         // Parse the returned results. 
         if (tcs.task.error) {
             NSLog(@"get token error: %@", tcs.task.error);
             return nil;
         } else {
             // The returned data is in the JSON format. Parse the data to obtain the values of the fields of the token. 
             NSDictionary * object = [NSJSONSerialization JSONObjectWithData:tcs.task.result
                                                                     options:kNilOptions
                                                                       error:nil];
             OSSFederationToken * token = [OSSFederationToken new];
             token.tAccessKey = [object objectForKey:@"AccessKeyId"];
             token.tSecretKey = [object objectForKey:@"AccessKeySecret"];
             token.tToken = [object objectForKey:@"SecurityToken"];
             token.expirationTimeInGMTFormat = [object objectForKey:@"Expiration"];
             NSLog(@"get token: %@", token);
             return token;
         }
     }];

Self-signed mode

Signed URLs