存取控制 - SDK示例

移動終端是一個不受信任的環境。為此，SDK提供了兩種依賴於您的業務Server的鑒權模式： STS鑒權模式 和 自簽名模式 。

STS鑒權模式

介紹

OSS可以通過阿里雲STS服務，臨時進行授權訪問。阿里雲STS (Security Token Service) 是為雲端運算使用者提供臨時存取權杖的Web服務。通過STS，您可以為第三方應用或聯邦使用者（使用者身份由您自己管理）頒發一個自訂時效和許可權的訪問憑證，App端稱為FederationToken。第三方應用或聯邦使用者可以使用該訪問憑證直接調用阿里雲產品API，或者使用阿里雲產品提供的SDK來訪問雲產品API。

您不需要透露您的長期密鑰(AccessKey)給第三方應用，只需要生成一個存取權杖並將令牌交給第三方應用即可。這個令牌的存取權限及有效期間限都可以由您自訂。
您不需要關心許可權撤銷問題，存取權杖過期後就自動失效。

以APP應用為例，互動流程如下圖：

方案的詳細描述如下：

App使用者登入。App使用者身份是您自己管理。您可以自訂身份管理系統，也可以使用外部Web帳號或OpenID。對於每個有效App使用者來說，AppServer可以確切地定義出每個App使用者的最小存取權限。
AppServer請求STS服務獲取一個安全性權杖(SecurityToken)。在調用STS之前，AppServer需要確定App使用者的最小存取權限（用Policy文法描述）以及授權的過期時間。然後通過調用STS的AssumeRole(扮演角色)介面來獲取安全性權杖。角色管理與使用相關內容請參考RAM使用指南中的角色管理。
STS返回給AppServer一個有效訪問憑證，App端稱為FederationToken，包括一個安全性權杖(SecurityToken)、臨時存取金鑰(AccessKeyId, AccessKeySecret)以及過期時間。
AppServer將FederationToken返回給ClientApp。ClientApp可以緩存這個憑證。當憑證失效時，ClientApp需要向AppServer申請新的有效訪問憑證。比如，訪問憑證有效期間為1小時，那麼ClientApp可以每30分鐘向AppServer請求更新訪問憑證。
ClientApp使用本機快取的FederationToken去請求Aliyun Service API。雲端服務會感知STS訪問憑證，並會依賴STS服務來驗證訪問憑證，並正確響應使用者請求。

STS安全性權杖詳情，請參考《RAM使用指南》中的角色管理。關鍵是調用STS服務介面AssumeRole來獲取有效訪問憑證即可。也可以直接使用STS SDK來調用該方法，點擊查看。

使用這種模式授權需要先開通阿里雲RAM服務。

STS使用手冊：點擊查看

OSS授權策略配置：點擊查看

直接設定StsToken

您可以在APP中，預先通過某種方式(如通過網路請求從您的業務Server上)獲取一對StsToken，然後用它來初始化SDK。採取這種使用方式，您需要格外關注StsToken的過期時間，在StsToken即將過期時，需要您主動更新新的StsToken到SDK中。

初始化代碼為：

String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

在您判斷到Token即將過期時，您可以重新構造新的OSSClient，也可以通過如下方式更新CredentialProvider:

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

實現獲取StsToken回調

如果您期望SDK能自動幫您管理Token的更新，那麼，您需要告訴SDK如何獲取Token。在SDK的應用中，您需要實現一個回調，這個回調通過您實現的方式去獲取一個Federation Token(即StsToken)，然後返回。SDK會利用這個Token來進行加簽處理，並在需要更新時主動調用這個回調獲取Token，如圖示：

String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
OSSCredentialProvider credentialProvider = new OSSFederationCredentialProvider() {
    @Override
    public OSSFederationToken getFederationToken() {
        // 您需要在這裡實現獲取一個FederationToken，並構造成OSSFederationToken對象返回
        // 如果因為某種原因獲取失敗，可直接返回nil
        OSSFederationToken * token;
        // 下面是一些獲取token的代碼，比如從您的server獲取
        ...
        return token;
    }
};
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

此外，如果您已經通過別的方式拿到token所需的各個欄位，也可以在這個回調中直接返回。如果這麼做的話，您需要自己處理token的更新，更新後重新設定該OSSClient執行個體的OSSCredentialProvider。

使用樣本：

假設您搭建的server地址為: http://localhost:8080/distribute-token.json ，並假設訪問這個地址，返回的資料如下：

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

那麼，您可以這麼實現一個OSSFederationCredentialProvider執行個體：

OSSCredentialProvider credetialProvider = new OSSFederationCredentialProvider() {
    @Override
    public OSSFederationToken getFederationToken() {
        try {
            URL stsUrl = new URL("http://localhost:8080/distribute-token.json");
            HttpURLConnection conn = (HttpURLConnection) stsUrl.openConnection();
            InputStream input = conn.getInputStream();
            String jsonText = IOUtils.readStreamAsString(input, OSSConstants.DEFAULT_CHARSET_NAME);
            JSONObject jsonObjs = new JSONObject(jsonText);
            String ak = jsonObjs.getString("AccessKeyId");
            String sk = jsonObjs.getString("AccessKeySecret");
            String token = jsonObjs.getString("SecurityToken");
            String expiration = jsonObjs.getString("Expiration");
            return new OSSFederationToken(ak, sk, token, expiration);
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }
};

自簽名模式

您可以把AccessKeyId/AccessKeySecret保存在您的業務server，然後在SDK實現回調，將需要加簽的合并好的簽名串POST到server，您在業務server對這個串按照OSS規定的簽名演算法簽名之後，返回給該回呼函數，再由回調返回。

簽名演算法參考：點擊查看

content是已經根據請求各個參數拼接後的字元串，所以演算法為：

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

代碼如下：

String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
credentialProvider = new OSSCustomSignerCredentialProvider() {
    @Override
    public String signContent(String content) {
        // 您需要在這裡依照OSS規定的簽名演算法，實現加簽一串字元內容，並把得到的簽名傳拼接上AccessKeyId後返回
        // 一般實現是，將字元內容post到您的商務服務器，然後返回簽名
        // 如果因為某種原因加簽失敗，描述error資訊後，返回nil
        // 以下是用本地演算法進行的示範
        return "OSS " + AccessKeyId + ":" + base64(hmac-sha1(AccessKeySecret, content));
    }
};
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

特別注意：無論是STS鑒權模式，還是自簽名模式，您實現的回呼函數，都需要保證調用時返回結果。所以，如果您在其中實現了向業務server獲取token、signature的網路請求，建議調用網路程式庫的同步介面。回調都是在SDK具體請求的時候，在請求的子線程中執行，所以不會阻塞主線程。