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 application 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 contain a security token and a temporary AccessKey pair. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. 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.

   • Method 2

     Use STS SDKs. 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

   You can use OSSAuthCredentialProvider to initialize OSS SDK for iOS. For more information, see Initialization.

   When you initialize the SDK by using temporary access credentials, take note of the validity period of the STS token. The following sample code provides an example on how to determine the validity period of an STS 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 STS 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 STS token

     When the STS 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 STS token

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

     id<OSSCredentialProvider> credential = [[OSSFederationCredentialProvider alloc] initWithFederationTokenGetter:^OSSFederationToken * {
         // Implement a function that obtains a federation token and returns it as 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 STS 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 sample response 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 application 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;
         }
     }];

Signed URLs