IBM Cloud サービス API の呼び出し

サービスの API での認証のための IBM Cloud IAM トークンの引き渡し

IAM アクセス・トークンを取得するには、まず、API クライアントは IBM Cloud IAM API を呼び出して、そのトークンを認証および取得する必要があります。 IBM Cloud サービス API クライアント向けの推奨される方法は、IBM Cloud API キーを使用して IAM アクセス・トークンを取得することです。 JSON Web Tokenとして実装された IAM アクセス・トークンは、認証方式として IAM アクセス・トークンを受け入れる IBM Cloud サービスの複数の呼び出しに使用できます。 IAM アクセス・トークンは非対称鍵でデジタル署名されるため、IBM Cloud サービスは、外部サービスを何も呼び出さずに IAM アクセス・トークンを検証できます。 これにより、API 呼び出しのパフォーマンスが大幅に向上します。

アクセス・トークンを使用してサービスの API で認証するには、以下の手順を実行します。

1. まず、IBM Cloud API キーを作成します (まだ作成していない場合)。
2. API クライアントが行う次のステップは、『API キーを使用した IAM トークンの取得』の説明に従って IAM アクセス・トークンを取得することです。
3. 応答から、プロパティーaccess_tokenを抽出して IAM アクセス・トークンを取得します。expires_in は、IAM アクセス・トークンaccess_tokenの有効期限が切れるまでの秒数を示します。 この相対値を使用するか、 expiration UNIX 時刻に基づく絶対タイム・スタンプを使用してください。
4. 以下の説明に従って、IAM アクセス・トークンを送信します。RFC 6750、セクション 2.1。 許可要求ヘッダー・フィールド:

次の例を検討してください。

1. HTTP ヘッダー Authorization を使用します。
2. IAM アクセス・トークンに接頭部としてリテラル Bearer eyJhbGciOiJSUzI1Ng... を付加します。
3. 接頭部を付けた IAM アクセス・トークンを HTTP ヘッダーに追加します: Authorization: Bearer eyJhbGciOiJSUzI1Ng...。

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1Ng..."

import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import <sdk_base_package>.ExampleService.v1.ExampleService;
...
String bearerToken = // ... obtain bearer token value ...

// Create the authenticator.
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator(bearerToken);

// Create the service instance.
ExampleService service = new ExampleService(authenticator);

// 'service' can now be used to invoke operations.
...
// Later, if your bearer token value expires, you can set a new one like this:
newToken = // ... obtain new bearer token value
authenticator.setBearerToken(newToken);

const ExampleServiceV1 = require('mysdk/example-service/v1');
const { BearerTokenAuthenticator } = require('mysdk/auth');

const authenticator = new BearerTokenAuthenticator({
  bearerToken: '<access-token>',
});

const myService = new ExampleServiceV1({
  authenticator,
});
...

// Later when the access token expires, the application must acquire
// a new access token, then set it on the authenticator.
// Subsequent request invocations will include the new access token.
authenticator.setBearerToken('<new-access-token>')

from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator

authenticator = BearerTokenAuthenticator(<your_bearer_token>)
service = ExampleService(authenticator=authenticator)

# after getting a new access token...
service.get_authenticator().set_bearer_token('54321');

    import {
    "github.com/IBM/go-sdk-core/v5/core"
    "<appropriate-git-repo-url>/exampleservicev1"
}
...
// Create the authenticator.
bearerToken := // ... obtain bearer token value ...
authenticator := &core.BearerTokenAuthenticator{
    BearerToken: bearerToken,
}

// Create the service options struct.
options := &exampleservicev1.ExampleServiceV1Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service := exampleservicev1.NewExampleServiceV1(options)

// 'service' can now be used to invoke operations.
...
// Later, if your bearer token value expires, you can set a new one like this:
newToken := // ... obtain new bearer token value
authenticator.BearerToken = newToken

同じ IAM アクセス・トークンを後続の IBM Cloud サービス API 呼び出しに使用することで、最高のパフォーマンスとスケーラビリティーを実現できます。

Java SDK リファレンス

Node SDK リファレンス

Python SDK リファレンス

Go SDK リファレンス

サービス API での認証のための IBM Cloud API キーの引き渡し

API クライアントは、ターゲット・サービスの API に IBM Cloud API キーを直接渡すことができます。 これを行うには、基本許可 HTTP ヘッダーを使用して、ユーザー名として apikey キーワードを、パスワードとして IBM Cloud API キーをターゲット・サービスに送信します。

API キーをサービス API に渡すすべてのケースで、サービス ID の API キーを使用すること、または特定のサービスを使用するために必要なレベルのアクセス権限だけが割り当てられた機能 ID に関連付けられているユーザー API キーを使用することをお勧めします。

ターゲット・サービス API は、IBM Cloud IAM サービスを使用して、IBM Cloud API キーをイントロスペクトする必要があります。 以下の図は、3 つの API 相互作用を示しています。 IBM Cloud API キーは各ターゲット・サービスの API に渡されるため、各ターゲット・サービスが IBM Cloud IAM を呼び出して IBM Cloud API キー詳細を検索する必要があります。

IBM Cloud API キーの使用は便利であり、新しい API を見つけてプロトタイプを素早く試してみることが容易になります。 この方法では、IBM Cloud API キーを読み取り可能な形式でターゲット・サービスの API に送信する必要があるため、API キーが不必要に漏えいされます。 さらに、ターゲット・サービスの API は必ず API キーをイントロスペクトする必要があるため、この方法は効率的ではなく、従って実動ワークロードには推奨されません。

API キーを使用してサービスの API で認証するには、以下の手順を実行します。

1. まず、IBM Cloud API キーを作成します (まだ作成していない場合)。
2. RFC 7617 で定義されているように、 IBM Cloud API キーを HTTP ヘッダー「Authorization」として送信します。 ユーザー名として apikey を、パスワードとして API キー値を使用します。

例えば、以下の手順では API キーが 0a1A2b3B4c5C6d7D8e9E であると想定しています。

1. ユーザー名 apikey と API キーをコロンで区切って連結します: apikey:0a1A2b3B4c5C6d7D8e9E
2. このストリングを Base64 エンコード処理します: base64("apikey:0a1A2b3B4c5C6d7D8e9E") => YXBpa2V5OjBhMUEyYjNCNGM1QzZkN0Q4ZTlF
3. HTTP ヘッダー Authorization をスキーマ Basic を使用して設定します (例えば、Authorization: Basic YXBpa2V5OjBhMUEyYjNCNGM1QzZkN0Q4ZTlF)。

curl -u "apikey:<IBM Cloud API key value>"

import com.ibm.cloud.sdk.core.security.BasicAuthenticator;
import <sdk_base_package>.ExampleService.v1.ExampleService;
...
// Create the authenticator.
BasicAuthenticator authenticator = new BasicAuthenticator.Builder()
    .username("myuser")
    .password("mypassword")
    .build();

// Create the service instance.
ExampleService service = new ExampleService(authenticator);

// 'service' can now be used to invoke operations.

from ibm_cloud_sdk_core.authenticators import BasicAuthenticator

authenticator = BasicAuthenticator(<your_username>, <your_password>)
service = ExampleService(authenticator=authenticator)

import {
    "github.com/IBM/go-sdk-core/v5/core"
    "<appropriate-git-repo-url>/exampleservicev1"
}
...
// Create the authenticator.
authenticator := &core.BasicAuthenticator{
    Username: "myuser",
    Password: "mypassword",
}

// Create the service options struct.
options := &exampleservicev1.ExampleServiceV1Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service := exampleservicev1.NewExampleServiceV1(options)

// 'service' can now be used to invoke operations.

ユーザー名は apikey で、パスワードは API キー自体です。