ダイレクトライン API 3.0 での認証Authentication in Direct Line API 3.0

クライアントは、Direct Line API 3.0 に対する要求を、Bot Framework Portal の Direct Line チャネル構成ページから取得する シークレット を使用するか、ランタイム時に取得する トークン を使用して認証できます。A client can authenticate requests to Direct Line API 3.0 either by using a secret that you obtain from the Direct Line channel configuration page in the Bot Framework Portal or by using a token that you obtain at runtime. シークレットまたはトークンは、次の書式で各要求の Authorization ヘッダー内に指定する必要があります。The secret or token should be specified in the Authorization header of each request, using this format:

Authorization: Bearer SECRET_OR_TOKEN

シークレットとトークンSecrets and tokens

Direct Line シークレット は、関連付けられているボットに属するすべての会話にアクセスするために使用できるマスター キーです。A Direct Line secret is a master key that can be used to access any conversation that belongs to the associated bot. シークレット は、トークン を取得するために使用することもできます。A secret can also be used to obtain a token. シークレットには有効期限がありません。Secrets do not expire.

Direct Line トークン は、1 つの会話にアクセスするために使用できるキーです。A Direct Line token is a key that can be used to access a single conversation. トークンには有効期限がありますが、更新できます。A token expires but can be refreshed.

シークレット キーまたは トークン を使用するタイミングや、どちらを使用するかの決定は、セキュリティに関する考慮事項に基づいて行う必要があります。Deciding when or if to use the secret key or a token must be based on security considerations. シークレット キーの公開は、計画的に注意して行えば、許容される場合があります。Exposing the secret key could be acceptable if done intentionally and with care. 実際には、これが既定の動作です。これにより、クライアントが正当であるかどうかを Direct Line で判断できるためです。As matter of a fact, this is the default behavior because this allows Direct Line to figure out if the client is legitimate. ただし、一般に、ユーザー データを保持しようとしている場合は、セキュリティが問題になります。Generally speaking though, security is a concern if you're trying to persist user data. 詳細については、「セキュリティに関する考慮事項」セクションを参照してください。For more information, see section Security considerations.

サービス間アプリケーションを作成する場合は、Direct Line API 要求の Authorization ヘッダー内に シークレット を指定することが最も簡単な方法です。If you're creating a service-to-service application, specifying the secret in the Authorization header of Direct Line API requests may be simplest approach. クライアントが Web ブラウザーまたはモバイル アプリで実行されるアプリケーションを記述する場合は、シークレットをトークン (1 つの会話でのみ機能し、更新されない限り有効期限が切れます) と交換し、その トークン を、Direct Line API 要求の Authorization ヘッダー内に指定できます。If you're writing an application where the client runs in a web browser or mobile app, you may want to exchange your secret for a token (which only works for a single conversation and will expire unless refreshed) and specify the token in the Authorization header of Direct Line API requests. 自分にとって最適なセキュリティ モデルを選択してください。Choose the security model that works best for you.

注意

Direct Line クライアント資格情報は、ボットの資格情報とは異なります。Your Direct Line client credentials are different from your bot's credentials. これにより、キーを個別に変更でき、ボットのパスワードを公開せずにクライアント トークンを共有できます。This enables you to revise your keys independently and lets you share client tokens without disclosing your bot's password.

Direct Line シークレットを取得するGet a Direct Line secret

Azure portal で、ボット用の Direct Line チャネル構成ページを使用して、Direct Line シークレットを取得できます。You can obtain a Direct Line secret via the Direct Line channel configuration page for your bot in the Azure Portal:

Direct Line 構成

Direct Line トークンを生成するGenerate a Direct Line token

1 つの会話にアクセスするために使用できる Direct Line トークンを生成するには、まず Azure portal の Direct Line チャネル構成ページから Direct Line シークレットを取得します。To generate a Direct Line token that can be used to access a single conversation, first obtain the Direct Line secret from the Direct Line channel configuration page in the Azure Portal. その後、次の要求を発行して、Direct Line シークレットを Direct Line トークンと交換します。Then issue this request to exchange your Direct Line secret for a Direct Line token:

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer SECRET

この要求の Authorization ヘッダーの SECRET を、Direct Line シークレットの値に置き換えます。In the Authorization header of this request, replace SECRET with the value of your Direct Line secret.

以下のスニペットは、トークン生成要求と応答の例を示しています。The following snippets provide an example of the Generate Token request and response.

RequestRequest

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

要求ペイロードにはトークン パラメーターが含まれています。これは省略可能ですが、使用することをお勧めします。The request payload, which contains the token parameters, is optional but recommended. Direct Line サービスに送り返すことができるトークンを生成するときに、次のペイロードを提供して、接続セキュリティを強化します。When generating a token that can be sent back to the Direct Line service, provide the following payload to make the connection more secure. これらの値を含めることによって、Direct Line によるユーザー ID と名前の追加セキュリティ検証が実行可能になり、悪意のあるクライアントによるこれらの値の改ざんが禁止されます。By including these values, Direct Line can perform additional security validation of the user ID and name, inhibiting tampering of these values by malicious clients. これらの値を含めて、Direct Line の "会話更新" アクティビティ送信機能を向上させることもできます。これにより、ユーザーが会話に参加したときに直ちに会話更新を生成できるようになります。Including these values also improves Direct Line's ability to send the conversation update activity, allowing it to generate the conversation update immediately upon the user joining the conversation. この情報が指定されていない場合、ユーザーは、Direct Line が会話更新を送信する前に、コンテンツを送信する必要があります。When this information is not provided, the user must send content before Direct Line can send the conversation update.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
パラメーターParameter TypeType DescriptionDescription
user.id stringstring 省略可能。Optional. トークン内でエンコードするためのチャネル固有のユーザー ID。Channel-specific ID of the user to encode within the token. Direct Line ユーザーの場合、dl_ で始まる必要があります。For a Direct Line user, this must begin with dl_. 会話ごとに一意のユーザー ID を作成できます。セキュリティを強化するために、この ID は推測できないものにします。You can create a unique user ID for each conversation, and for better security, you should make this ID unguessable.
user.name stringstring 省略可能。Optional. トークン内でエンコードするためのユーザーの表示用フレンドリ名。The display-friendly name of the user to encode within the token.
trustedOrigins 文字列配列string array 省略可能。Optional. トークン内に埋め込む信頼されたドメインの一覧。A list of trusted domains to embed within the token. これらはボットの Web チャット クライアントをホストできるドメインです。These are the domains that can host the bot's Web Chat client. これはご自身のボット用の Direct Line 構成ページの一覧と一致する必要があります。This should match the list in the Direct Line configuration page for your bot.

ResponseResponse

要求が成功した場合、応答には、1 つの会話で有効な token と、このトークンの有効期限が切れるまでの秒数を示す expires_in 値が含まれます。If the request is successful, the response contains a token that is valid for one conversation and an expires_in value that indicates the number of seconds until the token expires. トークンを有効のままにするには、有効期限が切れる前にトークンを更新する必要があります。For the token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}

トークンの生成と会話の開始Generate Token versus Start Conversation

トークンの生成操作 (POST /v3/directline/tokens/generate) と会話の開始操作 (POST /v3/directline/conversations) は、どちらの操作も、1 つの会話にアクセスするために使用できる token を返すという点で類似しています。The Generate Token operation (POST /v3/directline/tokens/generate) is similar to the Start Conversation operation (POST /v3/directline/conversations) in that both operations return a token that can be used to access a single conversation. ただし、会話の開始操作とは異なり、トークンの生成操作では、会話は開始されず、ボットへの接触は行われず、WebSocket のストリーミング URL は作成されません。However, unlike the Start Conversation operation, the Generate Token operation does not start the conversation, does not contact the bot, and does not create a streaming WebSocket URL.

トークンをクライアントに配布し、クライアントに会話を開始してほしい場合は、トークンの生成操作を使用します。If you plan to distribute the token to clients and want them to initiate the conversation, use the Generate Token operation. 会話をすぐに開始するつもりの場合は、会話の開始操作を使用します。If you intend to start the conversation immediately, use the Start Conversation operation instead.

Direct Line トークンを更新するRefresh a Direct Line token

Direct Line トークンは、有効期限が切れていない限り、無制限に更新できます。A Direct Line token can be refreshed an unlimited amount of times, as long as it has not expired. 期限が切れたトークンは更新できません。An expired token cannot be refreshed. Direct Line トークンを更新するには、次の要求を発行します。To refresh a Direct Line token, issue this request:

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED

この要求の Authorization ヘッダーの TOKEN_TO_BE_REFRESHED を、更新する Direct Line トークンに置き換えます。In the Authorization header of this request, replace TOKEN_TO_BE_REFRESHED with the Direct Line token that you want to refresh.

以下のスニペットは、トークン更新要求と応答の例を示しています。The following snippets provide an example of the Refresh Token request and response.

RequestRequest

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

ResponseResponse

要求が成功した場合、応答には、前のトークンと同じ会話で有効な、新しい token と、新しいトークンの有効期限が切れるまでの秒数を示す expires_in 値が含まれます。If the request is successful, the response contains a new token that is valid for the same conversation as the previous token and an expires_in value that indicates the number of seconds until the new token expires. 新しいトークンを有効のままにするには、有効期限が切れる前にトークンを更新する必要があります。For the new token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Azure Bot Service 認証Azure Bot Service authentication

このセクションに記載されている情報は、「Azure Bot Service を介してボットに認証を追加する」の記事に基づいています。The information presented in this section is based on the Add authentication to your bot via Azure Bot Service article.

Azure Bot Service 認証 を使用すると、各種 ID プロバイダー (Azure Active DirectoryGitHubUber など) に対してユーザーを認証し、これらから アクセス トークン を取得できます。Azure Bot Service authentication enables you to authenticate users to and get access tokens from a variety of identity providers such as Azure Active Directory, GitHub, Uber and so on. カスタム OAuth2 ID プロバイダーの認証も構成できます。You can also configure authentication for a custom OAuth2 identity provider. これだけで、サポートされているすべての ID プロバイダーとチャネルで動作する 1 つの認証コード を作成できます。All this enables you to write one piece of authentication code that works across all supported identity providers and channels. これらの機能を利用するには、次の手順を実行する必要があります。To utilize these capabilities you need to perform the following steps:

  1. ボットで、ID プロバイダーでのアプリケーション登録の詳細を含む settings を静的に構成します。Statically configure settings on your bot that contains the details of your application registration with an identity provider.
  2. 前の手順で指定したアプリケーション情報に基づき、OAuthCard を使用して、ユーザーをサインインします。Use an OAuthCard, backed by the application information you supplied in the previous step, to sign-in a user.
  3. Azure Bot Service API を使用してアクセス トークンを取得します。Retrieve access tokens through Azure Bot Service API.

セキュリティに関する考慮事項Security considerations

Web チャットAzure Bot Service 認証 を使用する場合、注意する必要がある重要なセキュリティの考慮事項がいくつかあります。When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind.

  1. 偽装Impersonation. ここでの偽装とは、攻撃者がボットに自分を別人であると思い込ませることです。Impersonation here means an attacker makes the bot thinks he is someone else. Web チャットでは、攻撃者が自分の Web チャット インスタンスの ユーザー ID を変えて、他の誰かになりすます可能性があります。In Web Chat, an attacker can impersonate someone else by changing the user ID of his Web Chat instance. これを防ぐために、推奨事項として、ボット開発者は ユーザー ID を推測できないようにする 必要があります。To prevent this, it is recommend to bot developers to make the user ID unguessable.

    強化された認証 オプションを有効にすると、Azure Bot Service ではすべてのユーザー ID の変更を検出して、拒否できます。If you enable enhanced authentication options, Azure Bot Service can further detect and reject any user ID change. この場合、Direct Line からボットへのメッセージのユーザー ID (Activity.From.Id) は、Web チャットを初期化したときに使用したものと必ず同じになります。This means the user ID (Activity.From.Id) on messages from Direct Line to your bot will always be the same as the one you initialized the Web Chat with. この機能では、ユーザー ID は dl_ で始まる必要があることに注意してください。Note that this feature requires the user ID starts with dl_.

    注意

    トークンのシークレットを交換するときに User.Id が指定されている場合、その User.Id はトークンに埋め込まれます。When a User.Id is provided while exchanging a secret for a token, that User.Id is embedded in the token. Direct Line は、ボットに送信されたメッセージの ID がアクティビティの From.Id であることを確認します。クライアントが、別の From.Id を持つメッセージを Direct Line に送信すると、そのメッセージがボットに転送される前に、トークンの ID に変更されます。DirectLine makes sure the messages sent to the bot have that id as the activity's From.Id. If a client sends a message to DirectLine having a different From.Id, it will be changed to the Id in the token before forwarding the message to the bot. そのため、チャネル シークレットがユーザー ID で初期化された後は、別のユーザー ID を使用することはできません。So you cannot use another user id after a channel secret is initialized with a user id

  2. ユーザー IDUser identities. 次の 2 つのユーザー ID を取り扱う点に注意する必要があります。You must be aware that your are dealing with two user identities:

    1. チャネル内のユーザーの id。The user's identity in a channel.
    2. Bot が興味を持っている id プロバイダーのユーザー id。The user's identity in an identity provider that the bot is interested in.

    Bot が id プロバイダー P にサインインするためにユーザー A にチャネルを要求した場合、サインインプロセスでは、ユーザー A が P にサインインするものであることを確認する必要があります。別のユーザー B がサインインを許可されている場合、ユーザー A は bot を通じてユーザー B のリソースにアクセスできます。When a bot asks user A in a channel to sign-in to an identity provider P, the sign-in process must assure that user A is the one that signs into P. If another user B is allowed to sign-in, then user A would have access to user B's resource through the bot. Web チャットでは、次に説明するように、確実に適切なユーザーがサインインするために 2 つのメカニズムが用意されています。In Web Chat we have 2 mechanisms for ensuring the right user signed in as described next.

    1. 以前は、サインインの最後に、ランダムに生成された 6 桁のコード (別名マジック コード) がユーザーに表示されました。At the end of sign-in, in the past, the user was presented with a randomly generated 6-digit code (aka magic code). ユーザーは、サインイン プロセスを完了するために、サインインを開始したやり取りにおいて、このコードを入力する必要があります。The user must type this code in the conversation that initiated the sign-in to complete the sign-in process. このメカニズムでは、ユーザー エクスペリエンスが悪化する傾向があります。This mechanism tends to result in a bad user experience. また、フィッシング攻撃を受けやすくなります。Additionally, it is still susceptible to phishing attacks. 悪意のあるユーザーが、別のユーザーになりすましてサインインし、フィッシング詐欺を通じてマジック コードを入手できます。A malicious user can trick another user to sign-in and obtain the magic code through phishing.

    2. 前の方法で問題が発生したため、Azure Bot Service では、マジック コードが不要になりました。Because of the issues with the previous approach, Azure Bot Service removed the need for the magic code. Azure Bot Service では、サインイン プロセスは必ず Web チャット自体と 同じブラウザー セッション でのみ完了します。Azure Bot Service guarantees that the sign-in process can only be completed in the same browser session as the Web Chat itself. この保護を有効にするには、bot 開発者として、 bot の Web チャットクライアントをホストできる信頼されたドメインの一覧 を含む 直接ライントークン を使用して、Web chat を開始する必要があります。To enable this protection, as a bot developer, you must start Web Chat with a Direct Line token that contains a list of trusted domains that can host the bot's Web Chat client. 以前は、ドキュメントに記載されていないオプション パラメーターを Direct Line トークン API に渡すことでのみ、このトークンを取得できました。Before, you could only obtain this token by passing an undocumented optional parameter to the Direct Line token API. 現在は、強化された認証オプションを使用して、Direct Line 構成ページで信頼されたドメイン (origin) の一覧を静的に指定できます。Now, with enhanced authentication options, you can statically specify the trusted domain (origin) list in the Direct Line configuration page.

    Azure Bot Service を介してボットに認証を追加する」も参照してください。See also Add authentication to your bot via Azure Bot Service.

コード例Code examples

次の .NET コントローラーは、強化された認証オプションが有効な状態で動作し、Direct Line トークンとユーザー ID を返します。The following .NET controller works with enhanced authentication options enabled and returns a Direct Line Token and user ID.

public class HomeController : Controller
{
    public async Task<ActionResult> Index()
    {
        var secret = GetSecret();

        HttpClient client = new HttpClient();

        HttpRequestMessage request = new HttpRequestMessage(
            HttpMethod.Post,
            $"https://directline.botframework.com/v3/directline/tokens/generate");

        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", secret);

        var userId = $"dl_{Guid.NewGuid()}";

        request.Content = new StringContent(
            JsonConvert.SerializeObject(
                new { User = new { Id = userId } }),
                Encoding.UTF8,
                "application/json");

        var response = await client.SendAsync(request);
        string token = String.Empty;

        if (response.IsSuccessStatusCode)
        {
            var body = await response.Content.ReadAsStringAsync();
            token = JsonConvert.DeserializeObject<DirectLineToken>(body).token;
        }

        var config = new ChatConfig()
        {
            Token = token,
            UserId = userId
        };

        return View(config);
    }
}

public class DirectLineToken
{
    public string conversationId { get; set; }
    public string token { get; set; }
    public int expires_in { get; set; }
}
public class ChatConfig
{
    public string Token { get; set; }
    public string UserId { get; set; }
}

次の JavaScript コントローラーは、強化された認証オプションが有効な状態で動作し、Direct Line トークンとユーザー ID を返します。The following JavaScript controller works with enhanced authentication options enabled and returns a Direct Line Token and user ID.

var router = express.Router(); // get an instance of the express Router

// Get a directline configuration (accessed at GET /api/config)
const userId = "dl_" + createUniqueId();

router.get('/config', function(req, res) {
    const options = {
        method: 'POST',
        uri: 'https://directline.botframework.com/v3/directline/tokens/generate',
        headers: {
            'Authorization': 'Bearer ' + secret
        },
        json: {
            User: { Id: userId }
        }
    };

    request.post(options, (error, response, body) => {
        if (!error && response.statusCode < 300) {
            res.json({
                    token: body.token,
                    userId: userId
                });
        }
        else {
            res.status(500).send('Call to retrieve token from Direct Line failed');
        }
    });
});

その他のリソースAdditional resources