Access control

Last Updated: Sep 28, 2017

Mobile terminals are an untrusted environment. Therefore, the SDK provides two authentication modes based on your servers: STS authentication mode and self-signed mode.

STS authentication mode


OSS can temporarily grant authorization for access using the Alibaba Cloud STS service. Alibaba Cloud STS (Security Token Service) is a web service that provides a temporary access token to a cloud computing user.

Through the STS, you can assign a third-party application or federated user (you can manage the user ID) an access credential with a custom validity period and permissions. The access credential is called FederationToken on the app side.

Third-party applications or federated users can use these access credentials to directly call the Alibaba Cloud product APIs or use the SDKs provided by Alibaba Cloud products to access the cloud product APIs.

  • You do not need to expose your long-term key (AccessKey) to a third-party application. You only need to generate an access token and send the access token to the third-party application. You can customize the access permission and validity of this token.

  • You do not need to worry about permission revocation issues. The access token automatically becomes invalid when it expires.

Taking an app as an example, the interaction process is shown in the following figure:


The solution is detailed as follows:

  1. Log on as the app user. App user IDs are managed by yourself. You can customize the ID management system or use an external web account or OpenID. For each valid app user, the AppServer can precisely define the minimum access permission.

  2. The AppServer requests a security token (SecurityToken) from the STS. Before calling STS, the AppServer needs to determine the minimum access permission (described in policy syntax) of the app user and the expiration time of the authorization. Then you can obtain the security token by calling the STS’ AssumeRole interface. For details about role management and usage, see Role Management in the RAM User Guide.

  3. The STS returns a valid access credential (called FederationToken on the app side) to the AppServer. The access credential contains a security token, a temporary pair of access keys (an AccessKeyID and an AccessKeySecret), and the expiration time.

  4. The AppServer returns the FederationToken to the ClientApp. The ClientApp can cache this credential. When the credential becomes invalid, the ClientApp needs to request a new valid access credential from the AppServer. For example, if the access credential is valid for one hour, the ClientApp can request the AppServer to update the access credential every 30 minutes.

  5. The ClientApp uses the locally cached FederationToken to request Alibaba Cloud Service APIs. The cloud service perceives the STS access credential, relies on STS to verify the credential, and responds to the user request correctly.

For details about STS security tokens, see Role Management in the RAM User Guide. The key is to call the STS interface AssumeRole to obtain valid access credential. You can also directly use STS SDK to call this method. Click to view details.

To use this authentication mode, you need to first activate Alibaba Cloud RAM service.

STS User Manual: Click to view details.

OSS authentication policy configuration: Click to view details.

Set StsToken directly

You can get a pair of StsToken in the app via a method (such as from your business server through network requests) and then use it to initialize the SDK. If this method is adopted, you must pay particular attention to the expiration time of the StsToken. When the StsToken is about to expire, you need to take initiative to update the new StsToken to the SDK.

The initial code is:

  1. String endpoint = "";
  2. OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
  3. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

When you see that the Token is about to expire, you can rebuild a new OSSClient, or update the CredentialProvider by the following method :

  1. oss.updateCredentialProvider(new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>"));

Implement the callback to get the StsToken

If you want the SDK to automatically help you manage Token updates, you should tell the SDK how to get the token. In the SDK’s app, you need to implement a callback which gets a FederationToken (that is, StsToken) and returns the token. The SDK will use the Token for signing. When the token needs to be updated, the SDK will call the callback to get the token, as shown in the figure:

  1. String endpoint = "";
  2. OSSCredentialProvider credentialProvider = new OSSFederationCredentialProvider() {
  3. @Override
  4. public OSSFederationToken getFederationToken() {
  5. // Here you need to implement a method to get a FederationToken and construct it into the OSSFederationToken object to return it
  6. // If the token fails to be obtained, "nil" is returned directly
  7. OSSFederationToken * token;
  8. // The following code obtains the token, from your server for example:
  9. ...
  10. return token;
  11. }
  12. };
  13. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

In addition, if you have obtained all the fields required by the token by other means, you can use the callback to directly return the token. In this case, you need to manually update the token and then re-set the OSSCredentialProvider of the OSSClient instance.


Suppose the URL of the server you set up is: http://localhost:8080/distribute-token.json. If you access the address, the returned data is shown as follows:

  1. {"accessKeyId":"STS.iA645eTOXEqP3cg3VeHf",
  2. "accessKeySecret":"rV3VQrpFQ4BsyHSAvi5NVLpPIVffDJv4LojUBZCf",
  3. "expiration":"2015-11-03T09:52:59Z",
  4. "federatedUser":"335450541522398178:alice-001",
  5. "requestId":"C0E01B94-332E-4582-87F9-B857C807EE52",
  6. "securityToken":"CAES7QIIARKAAZPlqaN9ILiQZPS+JDkS/GSZN45RLx4YS/p3OgaUC+oJl3XSlbJ7StKpQ...."}

You can use the following code to implement the ‘OSSFederationCredentialProvider’ instance:

  1. OSSCredentialProvider credetialProvider = new OSSFederationCredentialProvider() {
  2. @Override
  3. public OSSFederationToken getFederationToken() {
  4. try {
  5. URL stsUrl = new URL("http://localhost:8080/distribute-token.json");
  6. HttpURLConnection conn = (HttpURLConnection) stsUrl.openConnection();
  7. InputStream input = conn.getInputStream();
  8. String jsonText = IOUtils.readStreamAsString(input, OSSConstants.DEFAULT_CHARSET_NAME);
  9. JSONObject jsonObjs = new JSONObject(jsonText);
  10. String ak = jsonObjs.getString("accessKeyId");
  11. String sk = jsonObjs.getString("accessKeySecret");
  12. String token = jsonObjs.getString("securityToken");
  13. String expiration = jsonObjs.getString("expiration");
  14. return new OSSFederationToken(ak, sk, token, expiration);
  15. } catch (Exception e) {
  16. e.printStackTrace();
  17. }
  18. return null;
  19. }
  20. };

Self-signed mode

You can store the AccessKeyID and AccessKeySecret to your business server and then obtain them by using a callback function in the SDK. Post the merged signature string to be signed to the server, sign the string using the OSS-specified signature algorithm on the business server, and transfer the signed string to the callback function which will return the string.

Signature algorithm reference: Click to view details.

The content is a character string merged according to various request parameters. The algorithm is:

  1. signature = "OSS " + AccessKeyId + ":" + base64(hmac-sha1(AccessKeySecret, content))

As follows:

  1. String endpoint = "";
  2. credentialProvider = new OSSCustomSignerCredentialProvider() {
  3. @Override
  4. public String signContent(String content) {
  5. // Here you need to sign a character string using the OSS-specified signature algorithm, merge the AccessKeyID with the signed string, and return the string
  6. // A typical implementation method is to post the character string to your business server and then return the signature
  7. // If the signing fails for some reason, "nil" will be returned after the error is described
  8. // The following is a demo using a local algorithm for signing
  9. return "OSS " + AccessKeyId + ":" + base64(hmac-sha1(AccessKeySecret, content));
  10. }
  11. };
  12. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

Special notes: For STS authentication mode and self-signed mode, you should ensure that the results will be returned at the time that you call the implemented callback function. Therefore, if you need to obtain the token and signature from the business server through a network request, we recommend that you call the synchronous interface of the network library. Callback is executed in the subthread of the request from the SDK, which does not block the main thread.

Thank you! We've received your feedback.