API認証
すべてのAPIリクエストは、Authorizationヘッダーを通じて認証する必要があります。NTT CPaaS APIでは、以下の認証方法をご利用いただけます：
- HTTPベーシック認証
- APIキー
- IBSSOトークン
- OAuth 2.0
現在の技術スタックとセキュリティ要件レベルに合わせて、お好みの方法を選択してください。これらの方法の多くは中間者攻撃に対して脆弱であるため、暗号化された接続やSSLなどの他のセキュリティ対策と組み合わせて導入することをお勧めします。
発生しうる潜在的な問題について確認したい時は、トラブルシューティングを行うか、NTT CPaaSのサポートチームまでお問い合わせください。
ベーシック
ベーシック認証は、すべてのAPIリクエストにユーザー名とパスワードを送信することで機能します。通常、この方法はAPIキーが利用できない場合に使用されます。例えば、APIキーを生成するAPIメソッドでは、ベーシック認証によって認証を行うことができます。
ベーシック認証は、暗号化された資格情報を元の値に戻すのが未だに容易なため、最も推奨されていない方法です。ベージック認証を使用してサーバーへのアクセスを制限する方法については、HTTP認証リソース について詳述しているドキュメントをご参照ください。
この方法に関するいくつかの重要な事実を次に示します：
- HTTPプロトコル自体に組み込まれています
- 資格情報は、Base64形式 (例えば、RFC2045-MIME バリアントを使用する場合など) でエンコードし、コロン (:) で区切る必要があります
- エンコードされた資格情報は、ヘッダーの
Basicの後に追加されます
例 - HTTPクライアント
NTT CPaaS APIのクライアントライブラリ のいずれかをご利用の場合、資格情報を手動でエンコードする必要はありません。クライアントオブジェクトのインスタンスを作成する際に、ユーザー名とパスワードを指定するだけで済みます。
REQUEST SAMPLES
curl
1
2 curl -L -g -X GET 'https://{baseUrl}/sms/2/text/advanced' /
3 -H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
java
1
2 String auth = username + ":" + password;
3 String encoded = Base64.getEncoder().encodeToString(auth.getBytes("UTF-8"));
4
5 String messageText = "This is test message sent using OkHttpClient and Basic auth";
6 String jsonBody = String.format(
7 "{\"messages\":[{\"from\":\"%s\",\"destinations\":[{\"to\":\"%s\"}],\"text\":\"%s\"}]}",
8 SENDER, PHONE_NUMBER, messageText);
9
10 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), jsonBody);
11
12 Request request = new Request.Builder()
13 .url(BASE_URL + "/sms/2/text/advanced")
14 .addHeader("Authorization", "Basic " + encoded)
15 .addHeader("Content-Type", "application/json")
16 .addHeader("Accept", "application/json")
17 .post(requestBody)
18 .build();
19
20 OkHttpClient httpClient = new OkHttpClient().newBuilder().build();
21 Response response = httpClient.newCall(request).execute();
22 System.out.println(response.body().string());
csharp
1
2 string username = "USERNAME";
3 string password = "PASSWORD";
4 string concatenated = $"{username}:{password}";
5 string encoded = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(concatenated));
6
7 HttpClient client = new HttpClient();
8 client.BaseAddress = new Uri("BASE_URL");
9 client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", encoded);
10 client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
例 - APIクライアントライブラリ
NTT CPaaS APIのクライアントライブラリ のいずれかをご利用の場合、上記の通り、資格情報を手動でエンコードする必要はありません。以下の例で示すように、クライアントオブジェクトのインスタンスを作成する際に、ユーザー名とパスワードを指定するだけで済みます。
csharp
1
2 var configuration = new Configuration()
3 {
4 BasePath = "BASE_URL",
5 Username = "USERNAME",
6 Password = "PASSWORD"
7 };
ベーシック認証のAPIスコープ [#api-scopes-on-basic-auth-basic]
ベーシック認証に関連するAPIスコープの詳細については、ユーザーロールとAPIスコープ について詳述しているセクションをご参照ください。
APIキーヘッダー
APIキーとは、クライアントがAPIコールを送信する際に提示するアクセストークンのことです。これはアクセスをセキュアに保つための簡便な方法であり、そのためREST APIで最も広く利用されている認証方式となっています。キーは、クエリ文字列またはリクエストヘッダーとして送信できます。アカウントを作成 すると、自動的にAPIキーが割り当てられます。より多くのキーを生成したり、既存のキーを管理したりしたい時は、NTT CPaaSのAPIキー管理 ページをご参照ください。
この方法に関するいくつかの重要な事実を次に示します：
- APIキーは、専用のAPIメソッドを呼び出すことで生成できます
- キーはいつでも無効化できるため、複数のアプリケーションまたはユースケース間でAPIへのアクセス権限を分離する際に便利です
- NTT CPaaSのAPIキーには、最終的に無効になる有効期限が事前定義されています
例 - HTTPクライアント
以下の例では、クライアントライブラリ をご利用の際に、APIキーの認証方法をいかに指定するかを示しています。
REQUEST SAMPLES
curl
1
2 curl -L -g -X GET 'https://{baseUrl}/sms/2/text/advanced' /
3 -H 'Authorization: App 003026abc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9'
java
1
2 Request request = new Request.Builder()
3 .url("BASE_URL" + "/sms/2/text/advanced")
4 .addHeader("Authorization", "App " + apiKey)
5 .addHeader("Content-Type", "application/json")
6 .addHeader("Accept", "application/json")
7 .post(requestBody)
8 .build();
csharp
1
2 HttpClient client = new HttpClient();
3 client.BaseAddress = new Uri("BASE_URL");
4
5 client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("App", "API_KEY");
6 client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
例 - APIクライアントライブラリ
以下の例は、APIキー認証を使用してHTTPリクエストを作成する方法を示しています。なお、このリクエストは、ベーシック認証リクエストを使用する場合よりもはるかに簡単です。
REQUEST SAMPLES
java
1
2 ApiClient apiClient = ApiClient.forApiKey(ApiKey.from(API_KEY))
3 .withBaseUrl(BaseUrl.from(BASE_URL))
4 .build();
csharp
1
2 var configuration = new Configuration()
3 {
4 BasePath = "BASE_URL",
5 ApiKeyPrefix = "App",
6 ApiKey = "API_KEY"
7 };
APIキーのAPIスコープ [#api-scopes-on-api-keys-api-key-header]
APIスコープの詳細については、APIスコープ について詳述しているセクションをご参照ください。
IBSSOトークンヘッダー
IBSSOトークンはセッションベースであるため、トークンの有効期間は短期間に留まります。これにより、最終的にはこの方法の安全性が高まりますが、認証を有効に保つためには、より多くのメンテナンスが必要となります。
通常、この種の認証は、システム全体で複数のサインインを回避したいシングルサインオンのシナリオで利用されます。また、機密データを様々な企業システムに分散させることなく、一元的に処理する必要があるシナリオにも有用な場合があります。
この方法に関するいくつかの重要な事実を次に示します：
- すべてのAPIリクエストは、セッショントークンで認証されます
- デフォルトでは、IBSSOトークンは60分後に失効するため、その後は新しいトークンを作成する必要があります
- 新しいトークンを作成したいが、前のトークンの有効期限がまだ切れていない場合は、最初にセッションを破棄する必要があります
- 専用のAPIコールでセッションの長さを短縮できます
IBSSOトークンの使い方 [#how-to-use-ibsso-tokens-ibsso-token-header]
- セッションエンドポイントを作成するコールを送信し、レスポンスからトークンを取得します。
- 後続のすべてのコールのAuthorizationヘッダーに
IBSSOとトークンを含めます：Authorization: IBSSO 2f9b4d31-2d0d-49a8-85f0-9b862bdca394 - 必要に応じて、セッションを破棄して、セッションの有効期間を調整することもできます。デフォルトでは、セッションは60分後に失効します。
HTTPリクエスト [#http-request-ibsso-token-header]
IBSSOトークンの取得 [#obtain-ibsso-token-ibsso-token-header]
Create session (セッション作成) エンドポイントを呼び出して、セッションを作成します。レスポンスには、 Send SMS (SMS送信) エンドポイントといったの他のAPIエンドポイントへのリクエストのHTTPヘッダーで使用できるトークンが含まれます。
REQUEST SAMPLES
java
1
2 private static class IbssoResponse {
3 public IbssoResponse() {
4 super();
5 }
6
7 @JsonProperty("token")
8 public String token;
9
10 @JsonGetter("token")
11 public String getToken() {
12 return token;
13 }
14
15 @JsonSetter("token")
16 public void setToken(String token) {
17 this.token = token;
18 }
19 }
20
21 String jsonBody = String.format("{\"username\":\"%s\",\"password\":\"%s\"}", "USERNAME", "PASSWORD");
22
23 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), jsonBody);
24
25 Request request = new Request.Builder()
26 .url("BASE_URL" + "/auth/1/session")
27 .addHeader("Content-Type", "application/json")
28 .addHeader("Accept", "application/json")
29 .post(requestBody)
30 .build();
31
32 OkHttpClient httpClient = new OkHttpClient().newBuilder().build();
33 Response response = httpClient.newCall(request).execute();
34 String responseBody = response.body().string();
35 System.out.println(responseBody);
36
37 IbssoResponse ibssoResponse = new ObjectMapper().readValue(responseBody, IbssoResponse.class);
38
39 return ibssoResponse.token;
csharp
1
2 public class IbssoResponse
3 {
4 [System.Text.Json.Serialization.JsonPropertyName("token")]
5 public string Token { get; set; }
6 }
7
8 string username = "USERNAME";
9 string password = "PASSWORD";
10
11 HttpClient client = new HttpClient();
12 client.BaseAddress = new Uri("BASE_URL");
13 client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
14
15 string body = $@"
16 {{
17 ""username"": ""{username}"",
18 ""password"": ""{password}""
19 }}";
20
21 HttpRequestMessage httpRequest = new HttpRequestMessage(HttpMethod.Post, "/auth/1/session");
22 httpRequest.Content = new StringContent(body, System.Text.Encoding.UTF8, "application/json");
23
24 var response = client.SendAsync(httpRequest).GetAwaiter().GetResult();
25 var responseContent = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
26
27 var responseObject = JsonSerializer.Deserialize(responseContent);
28
29 return responseObject.Token;
例 - HTTPクライアント
以下の例は、HTTPリクエストを準備する方法を示しています。この方法はAPIキー認証とほぼ同じですが、ヘッダーには App の代わりに IBBSO を使用します。
REQUEST SAMPLES
java
1
2 private static class IbssoResponse {
3 public IbssoResponse() {
4 super();
5 }
6
7 @JsonProperty("token")
8 public String token;
9
10 @JsonGetter("token")
11 public String getToken() {
12 return token;
13 }
14
15 @JsonSetter("token")
16 public void setToken(String token) {
17 this.token = token;
18 }
19 }
20
21 String jsonBody = String.format("{\"username\":\"%s\",\"password\":\"%s\"}", "USERNAME", "PASSWORD");
22
23 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), jsonBody);
24
25 Request request = new Request.Builder()
26 .url("BASE_URL" + "/auth/1/session")
27 .addHeader("Content-Type", "application/json")
28 .addHeader("Accept", "application/json")
29 .post(requestBody)
30 .build();
31
32 OkHttpClient httpClient = new OkHttpClient().newBuilder().build();
33 Response response = httpClient.newCall(request).execute();
34 String responseBody = response.body().string();
35 System.out.println(responseBody);
36
37 IbssoResponse ibssoResponse = new ObjectMapper().readValue(responseBody, IbssoResponse.class);
38
39 return ibssoResponse.token;
csharp
1
2 HttpClient client = new HttpClient();
3 client.BaseAddress = new Uri("BASE_URL");
4
5 client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("IBSSO", "TOKEN");
6 client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
例 - APIライブラリ
NTT CPaaSのAPIクライアントライブラリ を使用する場合は、APIキー認証と同じ要素が必要ですが、App の代わりに IBBSO を使用します。
csharp
1
2 var configuration = new Configuration()
3 {
4 BasePath = "BASE_URL",
5 ApiKeyPrefix = "IBSSO",
6 ApiKey = "TOKEN"
7 };
OAuth 2.0
この認証方式は最も安全な選択肢であり、事実上の業界標準となっています。IBSSOトークンを利用する場合と同様に、別のエンドポイントから取得したアクセストークンを使用することになります。
この方法に関するいくつかの重要な事実を次に示します：
- レスポンスで返されたアクセストークンは、同じレスポンスで秒単位で指定された制限時間内に期限切れになります。
- NTT CPaaSは、リソースサーバーおよび認証サーバーの両方の役割を果たします。
- トークンの有効期限が切れたら、新しいトークンを作成する必要があります。トークンの自動取得は行われません。
詳細については、公式の OAuth 2.0 仕様をご参照ください。
OAuth 2.0の使い方 [#how-to-use-oauth-20-oauth-20]
- 別のエンドポイントからアクセストークンと有効期限を取得するためにコールを送信します。
- トークンの有効期限が切れるまで、後続のすべてのコールのAuthorizationヘッダーに
Bearerとトークンを含めます。Authorization: Bearer eyJraWQiOiI5d29rWGRoSSIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJzdWIiOiJERDIwMjAiLCJpc3MiOiJpbmZvYmlwLmNvbSIsImV4cCI6MTYzMzAwNDQwNiwiaWF0IjoxNjMzMDAwODA2LCJqdGkiOiJiMmJmODgyMS01OTcxLTRiOTMtYWVmNy0zM2QwMDNkMjIxNjcifQ.KvIIOmCKJETiB6xKOqBxvZYnYOa8RAulYhChBEmI4Os
HTTPリクエスト [#http-request-oauth-20]
OAuthトークンの取得 [#obtain-oauth-token-oauth-20]
IBSSOトークンと同様に、APIコールを行う前に、まずトークンを取得する必要があります。
REQUEST SAMPLES
java
1
2 private static class OauthResponse {
3 public OauthResponse() {
4 super();
5 }
6
7 @JsonProperty("access_token")
8 private String accessToken;
9 @JsonProperty("expires_in")
10 private String expiresIn;
11
12 @JsonGetter("access_token")
13 public String getAccessToken() {
14 return accessToken;
15 }
16
17 @JsonSetter("access_token")
18 public void setAccessToken(String accessToken) {
19 this.accessToken = accessToken;
20 }
21
22 @JsonGetter("expires_in")
23 public String getExpiresIn() {
24 return expiresIn;
25 }
26
27 @JsonSetter("expires_in")
28 public void setExpiresIn(String expiresIn) {
29 this.expiresIn = expiresIn;
30 }
31 }
32
33 HttpPost post = new HttpPost(BASE_URL + "/auth/1/oauth2/token");
34 List nvps = new ArrayList();
35 nvps.add(new BasicNameValuePair("client_id", username));
36 nvps.add(new BasicNameValuePair("client_secret", password));
37 nvps.add(new BasicNameValuePair("grant_type", "client_credentials"));
38
39 post.setEntity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8));
40
41 DefaultHttpClient httpClient = new DefaultHttpClient();
42 HttpResponse response = httpClient.execute(post);
43 System.out.println(response.getStatusLine());
44
45 String responseJson = EntityUtils.toString(response.getEntity());
46 System.out.println(responseJson);
47
48 OauthResponse oauthResponse = new ObjectMapper().readValue(responseJson, OauthResponse.class);
49
50 return oauthResponse.accessToken;
csharp
1
2 public class OauthResponse
3 {
4 [System.Text.Json.Serialization.JsonPropertyName("expires_in")]
5 public int ExpiresIn { get; set; }
6
7 [System.Text.Json.Serialization.JsonPropertyName("access_token")]
8 public string AccessToken { get; set; }
9 }
10
11 string username = "USERNAME";
12 string password = "PASSWORD";
13
14 HttpClient client = new HttpClient();
15 client.BaseAddress = new Uri("BASE_URL");
16
17 var dict = new Dictionary();
18 dict.Add("client_id", username);
19 dict.Add("client_secret", password);
20 dict.Add("grant_type", "client_credentials");
21
22 HttpRequestMessage httpRequest = new HttpRequestMessage(HttpMethod.Post, "/auth/1/oauth2/token");
23 httpRequest.Content = new FormUrlEncodedContent(dict);
24
25 var response = client.SendAsync(httpRequest).GetAwaiter().GetResult();
26 var responseContent = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
27
28 var responseObject = JsonSerializer.Deserialize(responseContent);
29
30 var accessToken = responseObject.AccessToken;
例 - HTTPクライアント
以下の例は、ヘッダーを含むHTTPクライアントリクエストを準備する方法を示しています。
REQUEST SAMPLES
java
1
2 Request request = new Request.Builder()
3 .url("BASE_URL" + "/sms/2/text/advanced")
4 .addHeader("Authorization", "Bearer " + accessToken)
5 .addHeader("Content-Type", "application/json")
6 .addHeader("Accept", "application/json")
7 .post(body)
8 .build();
csharp
1
2 HttpClient client = new HttpClient();
3 client.BaseAddress = new Uri("BASE_URL");
4
5 client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "ACCESS_TOKEN");
6 client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
例 - APIライブラリ
以下の例は、ヘッダーを含むHTTPリクエストを準備する方法を示しています。
csharp
1
2 var configuration = new Configuration()
3 {
4 BasePath = "BASE_URL",
5 ApiKeyPrefix = "Bearer",
6 ApiKey = "ACCESS_TOKEN"
7 };
エラー
通常、ユーザー名またはパスワードが見つからないか無効な場合、レスポンスには401 UnauthorisedがHTTPステータスコードとして表示されます。
json
1
2 {
3 "requestError": {
4 "serviceException": {
5 "messageId": "UNAUTHORIZED",
6 "text": "Invalid login details"
7 }
8 }
9 }
ライブラリの例外 [#library-exceptions-errors]
いずれかのライブラリ を使用する場合は、必ずAPI例外を処理するようにしてください。
REQUEST SAMPLES
java
1
2 try {
3 SmsResponse smsResponse = sendSmsApi.sendSmsMessage(smsMessageRequest);
4 } catch (ApiException apiException) {
5 apiException.getCode();
6 apiException.getResponseHeaders();
7 apiException.getResponseBody();
8 }
csharp
1
2 try
3 {
4 var result = api.SendSmsMessage(smsRequest);
5 }
6 catch(ApiException apiException)
7 {
8 var errorCode = apiException.ErrorCode;
9 var errorContent = apiException.ErrorContent;
10 }