Auth API リファレンス

Auth API は、Momento サービスの API キーとトークンを作成および管理します。これらの認証メカニズムは、1つ以上のキャッシュやトピックスへのアクセスを許可するために、1つ以上のパーミッションを持つようにスコープすることができます。

GenerateAuthToken API

指定した権限と有効期限を持つ新しい Momento Auth トークンを生成します。

名前	タイプ	説明
scope	TokenScope	新しいトークンに付与する権限。TokenScopeオブジェクトはSDKによって提供されます。
expiresIn	Number  |  ExpiresIn object	ExpiresIn.never()メソッド、ExpiresIn.minutes()メソッド、ExpiresIn.hours()メソッドを呼び出すことで、トークンが期限切れになるまでの秒数、またはその期間を表すExpiresInオブジェクト。

Method response object

• Success
  • authToken: string - 新しいAuthトークン
  • refreshToken: string - RefreshAuthToken API を使って、トークンの有効期限が切れる前にリフレッシュするためのトークン
  • endpoint: string - Momento クライアントがリクエストを行う際に使用する HTTP エンドポイント
  • expiresAt: Timestamp - トークンの有効期限が切れるタイムスタンプ
• Error

詳しくはレスポンスオブジェクトを参照してください。

注記

MomentoコントロールプレーンAPIにアクセスするためのトークンは、Momentoコンソールを使用してのみ生成できます。

RefreshAuthToken API

既存の有効期限が切れていない Momento Authトークンをリフレッシュします。 元のトークンと同じ権限と有効期限を持つ新しいトークンを生成します。

名前	タイプ	説明
refreshToken	String	GenerateAuthToken をコールした際に取得した、現在のAuthトークンの refreshToken。

Method response object

• Success
  • authToken: string - 新しいAuthトークン
  • refreshToken: string - RefreshAuthToken APIで使用するリフレッシュトークン。
  • endpoint: string - Momentoクライアントがリクエストを行う際に使用する HTTP エンドポイント。
  • expiresAt: Timestamp - トークンの有効期限が切れるタイムスタンプ
• Error

詳しくはレスポンスオブジェクトを参照してください。

TokenScope objects

名前	タイプ	説明
permissions	List <Permission>	新しいトークンに付与するパーミッション

TokenScopeは、パーミッションオブジェクトのリストです。このリストには、CachePermission 型または TopicPermission 型のパーミッションを含めることができ、最大 10 個のパーミッションオブジェクトを含めることができます。パーミッションは Momento データプレーン API (get や set など) へのアクセスのみを許可します。 複数のパーミッションオブジェクトを持つAuthトークンが作成された場合、一致するパーミッションがアクセスを許可します。たとえば、1 つのトークンに 2 つのパーミッションオブジェクトを設定した場合、次のようになります：

1. アカウントのすべてのキャッシュへの ReadWrite アクセスを許可するパーミッションオブジェクト
2. キャッシュ foo に対する ReadOnly アクセスを許可するパーミッションオブジェクト

この場合でも、トークンはキャッシュ foo に対してデータ操作 API (set、delete、DictionarySetFields など) を使用することができます。

Permission objects

これらのオブジェクトはキャッシュやトピック情報を持つ特定のロールを定義し、TokenScopeに割り当てられます。

CachePermission

キャッシュのパーミッションを定義する TokenScope オブジェクトのコンポーネント

名前	タイプ	説明
role	ReadOnly  |  ReadWrite  |  WriteOnly	パーミッションによって許可されたアクセスのタイプ
cache	AllCaches  |  CacheName	パーミッションは CacheName オブジェクトまたは AllCaches 組み込みの値を使用して、セレクトキャッシュの名前で制限することができます。

ロールの場合、CacheRole.ReadOnly を使用すると、CacheSelector で定義されたキャッシュ上のすべての読み取りデータプレーン API (get、DictionaryGetField など) にアクセスできるようになります。 CacheRole.ReadWrite を使用すると、CacheSelector で定義されたキャッシュ上のすべての読み取りデータプレーン API および書き込みデータプレーン API にアクセスできるようになります。 CacheRole.WriteOnly を使用すると、CacheSelector で定義されたキャッシュのすべての書き込みデータプレーン API にアクセスできるようになります。 CacheRole.WriteOnly は、SetIfNotExists のような条件付きの書き込みを意味する API や、ListPushBack が新しい長さを返すなど、コレクションの更新状態に関する情報を返す API には使用できません。カスタムロールはサポートされていません。

キャッシュの場合、値は組み込みの AllCaches か、このパーミッションのキャッシュ名を含む文字列となります。

CachePermission オブジェクトの TokenScope の例

これは、CachePermissions だけで TokenScope を作成する例です。

const CachePermissions = {
    permissions: [
        {
            role: CacheRole.ReadWrite, // Managed role
            cache: "MyCache" // grants access to a specific cache
        },
        {
            role: CacheRole.ReadOnly, // Managed role
            cache: AllCaches // Built-in value for access to all caches in the account.
        },
    ],
};

TopicPermission

トークンのパーミッションを定義するTokenScopeオブジェクトのコンポーネント

名前	タイプ	説明
role	SubscribeOnly | PublishSubscribe  |  PublishOnly	パーミッションによって許可されたアクセスのタイプ。
cache	AllCaches  |  CacheName	パーミッションは CacheName オブジェクトを使用して選択したキャッシュに制限することも、AllCaches 組み込み値を使用してアカウント内のすべてのキャッシュに制限することもできます。
topic	AllTopics  |  TopicName	パーミッションは TopicName オブジェクトを使用して選択したトピックに制限することも、 AllTopics 組み込み値を使用して上記のキャッシュ内のすべてのトピックに制限することもできます。

ロールには、TopicRole.PublishSubscribe、TopicRole.SubscribeOnly、TopicRole.PublishOnlyの3つの管理ロールがあります。カスタムロールはサポートされていません。SubscribeOnlyロールを使用するとトピックの購読のみが可能になり、PublishSubscribeロールを使用するとトピックの発行と購読が可能になり、PublishOnlyロールを使用するとトピックの発行のみが可能になります。

キャッシュでは、そのキャッシュの名前空間内のトピックのみがパーミッションによって許可されます。 これは組み込みの AllCaches 値またはキャッシュを指定する文字列に設定することができます。

トピックには、組み込みの AllTopics 値を設定することができます。 これは、cache で定義されているキャッシュ内のすべてのトピックにアクセスできるようにするもので、特定のトピック名を文字列で指定することもできます。

TopicPermissionオブジェクトのTokenScopeの例

これは、TopicPermissions だけで TokenScope を作成する例です。

const TopicsPermissions = {
    permissions: [
      {
        role: TopicRole.PublishSubscribe, // Managed role
        cache: 'the-great-wall', // grants access to a specific cache
        topic: 'highlights', // grants access to a specific topic
      },
      {
        role: TopicRole.SubscribeOnly, // Managed role
        cache: AllCaches, // This is a built-in value for access to all caches in the account
        topic: AllTopics, // This is a built-in value for access to all topic in the listed cache(s).
      },
    ],
};

GenerateDisposableToken API

指定した権限と有効期限を持つ、使い捨ての Momento Authトークンを生成します。

使い捨てトークンは、通常の Momento 認証トークンとはいくつかの点で異なります：

• 使い捨てトークンはコンソールで生成することはできません。generateDisposableToken`APIコールに使用するトークンは、Momentoコンソールから生成したスーパーユーザースコープのトークンでなければなりません。
• トークンの有効期限は1時間です。
• リフレッシュはできないので、リフレッシュトークンは付属しません。
• パーミッションは DisposableTokenScope オブジェクトで指定します。

名前	タイプ	説明
scope	DisposableTokenScope	新しい使い捨てトークンに付与する権限。SDK は、あらかじめ DisposableTokenScope オブジェクトを用意しています。
expiresIn	Number  |  ExpiresIn object	トークンが失効するまでの秒数、または ExpiresIn.minutes() メソッドや ExpiresIn.hours(1) メソッドを呼び出して期間を指定した ExpiresIn オブジェクト。使い捨てトークンは1時間以内に失効しなければなりません。

Method response object

• Success
  • authToken: string - 新しい使い捨てAuthトークン
  • endpoint: string - Momento クライアントがリクエストを行う際に使用する HTTP エンドポイント
  • expiresAt: Timestamp - トークンの有効期限が切れるタイムスタンプ
• Error

詳しくはレスポンスオブジェクトを参照してください。

JavaScript

// Generate a disposable token with read-write access to a specific key in one cache
const oneKeyOneCacheToken = await authClient.generateDisposableToken(
  DisposableTokenScopes.cacheKeyReadWrite('squirrels', 'mo'),
  ExpiresIn.minutes(30)
);
if (oneKeyOneCacheToken instanceof GenerateDisposableToken.Success) {
  console.log('Generated a disposable API key with access to the "mo" key in the "squirrels" cache!');
  // logging only a substring of the tokens, because logging security credentials is not advisable :)
  console.log(`API key starts with: ${oneKeyOneCacheToken.authToken.substring(0, 10)}`);
  console.log(`Expires At: ${oneKeyOneCacheToken.expiresAt.epoch()}`);
} else if (oneKeyOneCacheToken instanceof GenerateDisposableToken.Error) {
  throw new Error(
    `An error occurred while attempting to call generateApiKey with disposable token scope: ${oneKeyOneCacheToken.errorCode()}: ${oneKeyOneCacheToken.toString()}`
  );
}

// Generate a disposable token with read-write access to a specific key prefix in all caches
const keyPrefixAllCachesToken = await authClient.generateDisposableToken(
  DisposableTokenScopes.cacheKeyPrefixReadWrite(AllCaches, 'squirrel'),
  ExpiresIn.minutes(30)
);
if (keyPrefixAllCachesToken instanceof GenerateDisposableToken.Success) {
  console.log('Generated a disposable API key with access to keys prefixed with "squirrel" in all caches!');
  // logging only a substring of the tokens, because logging security credentials is not advisable :)
  console.log(`API key starts with: ${keyPrefixAllCachesToken.authToken.substring(0, 10)}`);
  console.log(`Expires At: ${keyPrefixAllCachesToken.expiresAt.epoch()}`);
} else if (keyPrefixAllCachesToken instanceof GenerateDisposableToken.Error) {
  throw new Error(
    `An error occurred while attempting to call generateApiKey with disposable token scope: ${keyPrefixAllCachesToken.errorCode()}: ${keyPrefixAllCachesToken.toString()}`
  );
}

// Generate a disposable token with read-only access to all topics in one cache
const allTopicsOneCacheToken = await authClient.generateDisposableToken(
  TokenScopes.topicSubscribeOnly('squirrel', AllTopics),
  ExpiresIn.minutes(30)
);
if (allTopicsOneCacheToken instanceof GenerateDisposableToken.Success) {
  console.log('Generated a disposable API key with access to all topics in the "squirrel" cache!');
  // logging only a substring of the tokens, because logging security credentials is not advisable :)
  console.log(`API key starts with: ${allTopicsOneCacheToken.authToken.substring(0, 10)}`);
  console.log(`Expires At: ${allTopicsOneCacheToken.expiresAt.epoch()}`);
} else if (allTopicsOneCacheToken instanceof GenerateDisposableToken.Error) {
  throw new Error(
    `An error occurred while attempting to call generateApiKey with disposable token scope: ${allTopicsOneCacheToken.errorCode()}: ${allTopicsOneCacheToken.toString()}`
  );
}

// Generate a disposable token with write-only access to a single topic in all caches
const oneTopicAllCachesToken = await authClient.generateDisposableToken(
  TokenScopes.topicPublishOnly(AllCaches, 'acorn'),
  ExpiresIn.minutes(30)
);
if (oneTopicAllCachesToken instanceof GenerateDisposableToken.Success) {
  console.log('Generated a disposable API key with access to all topics in the "squirrel" cache!');
  // logging only a substring of the tokens, because logging security credentials is not advisable :)
  console.log(`API key starts with: ${oneTopicAllCachesToken.authToken.substring(0, 10)}`);
  console.log(`Expires At: ${oneTopicAllCachesToken.expiresAt.epoch()}`);
} else if (oneTopicAllCachesToken instanceof GenerateDisposableToken.Error) {
  throw new Error(
    `An error occurred while attempting to call generateApiKey with disposable token scope: ${oneTopicAllCachesToken.errorCode()}: ${oneTopicAllCachesToken.toString()}`
  );
}

C#

// Generate a disposable token with read-write access to a specific key in one cache
var oneKeyOneCacheToken = await authClient.GenerateDisposableTokenAsync(
    DisposableTokenScopes.CacheKeyReadWrite("squirrels", "mo"),
    ExpiresIn.Minutes(30)
);

if (oneKeyOneCacheToken is GenerateDisposableTokenResponse.Success token1)
{
    // logging only a substring of the tokens, because logging security credentials is not advisable :)
    Console.WriteLine("The generated disposable token starts with: " + token1.AuthToken.Substring(0, 10));
    Console.WriteLine("The token expires at (epoch timestamp): " + token1.ExpiresAt.Epoch());
}
else if (oneKeyOneCacheToken is GenerateDisposableTokenResponse.Error err)
{
    Console.WriteLine("Error generating disposable token: " + err.Message);
}

// Generate a disposable token with read-write access to a specific key prefix in all caches
var keyPrefixAllCachesToken = await authClient.GenerateDisposableTokenAsync(
    DisposableTokenScopes.CacheKeyPrefixReadWrite(CacheSelector.AllCaches, "squirrel"),
    ExpiresIn.Minutes(30)
);

if (keyPrefixAllCachesToken is GenerateDisposableTokenResponse.Success token2)
{
    // logging only a substring of the tokens, because logging security credentials is not advisable :)
    Console.WriteLine("The generated disposable token starts with: " + token2.AuthToken.Substring(0, 10));
    Console.WriteLine("The token expires at (epoch timestamp): " + token2.ExpiresAt.Epoch());
}
else if (keyPrefixAllCachesToken is GenerateDisposableTokenResponse.Error err)
{
    Console.WriteLine("Error generating disposable token: " + err.Message);
}

// Generate a disposable token with read-only access to all topics in one cache
var allTopicsOneCacheToken = await authClient.GenerateDisposableTokenAsync(
    DisposableTokenScopes.TopicSubscribeOnly("squirrel", TopicSelector.AllTopics),
    ExpiresIn.Minutes(30)
);

if (allTopicsOneCacheToken is GenerateDisposableTokenResponse.Success token3)
{
    // logging only a substring of the tokens, because logging security credentials is not advisable :)
    Console.WriteLine("The generated disposable token starts with: " + token3.AuthToken.Substring(0, 10));
    Console.WriteLine("The token expires at (epoch timestamp): " + token3.ExpiresAt.Epoch());
}
else if (allTopicsOneCacheToken is GenerateDisposableTokenResponse.Error err)
{
    Console.WriteLine("Error generating disposable token: " + err.Message);
}

// Generate a disposable token with write-only access to a single topic in all caches
var oneTopicAllCachesToken = await authClient.GenerateDisposableTokenAsync(
    DisposableTokenScopes.TopicPublishOnly(CacheSelector.AllCaches, "acorn"),
    ExpiresIn.Minutes(30)
);

if (oneTopicAllCachesToken is GenerateDisposableTokenResponse.Success token4)
{
    // logging only a substring of the tokens, because logging security credentials is not advisable :)
    Console.WriteLine("The generated disposable token starts with: " + token4.AuthToken.Substring(0, 10));
    Console.WriteLine("The token expires at (epoch timestamp): " + token4.ExpiresAt.Epoch());
}
else if (oneTopicAllCachesToken is GenerateDisposableTokenResponse.Error err)
{
    Console.WriteLine("Error generating disposable token: " + err.Message);
}

DisposableTokenScope objects

名前	タイプ	説明
permissions	List <DisposableTokenCachePermission  |  Permission>	新しいトークンに付与するパーミッション

DisposableTokenScope オブジェクトは、CachePermission、TopicPermission、または DisposableTokenCachePermission タイプのパーミッション・オブジェクトを受け入れます。

DisposableTokenCachePermissions

DisposableTokenCachePermission は CachePermission を拡張したもので、CachePermission と同じフィールドを持ちますが、item フィールドが追加されています。

例えば、キーまたはキープレフィックスを表す文字列に item を設定すると、特定のキーまたはプレフィックスで始まるキーのセットのみにアクセスを制限できます。別の方法として、item を AllCacheItems に設定すると、通常の CachePermission と同じパーミッションのセットが作成されます。

名前	タイプ	説明
role	ReadOnly  |  ReadWrite  |  WriteOnly	パーミッションによって許可されるアクセスのタイプ
cache	AllCaches  |  CacheName	パーミッションは CacheName オブジェクトまたは AllCaches 組み込みの値を使用して、セレクトキャッシュの名前で制限することができます。
item	AllCacheItems  |  Key  |  KeyPrefix	パーミッションは、Key または KeyPrefix オブジェクト、あるいは AllCachesItems 組み込みの値を使用して、名前によるキャッシュアイテムの選択を制限することができます。

ロールの場合、CacheRole.ReadOnly を使用すると、CacheSelector で定義されたキャッシュ上のすべての読み取りデータプレーン API (get、DictionaryGetField など) にアクセスできるようになります。 CacheRole.ReadWrite を使用すると、CacheSelector で定義されたキャッシュ上のすべての読み取りデータプレーン API および書き込みデータプレーン API にアクセスできるようになります。 CacheRole.WriteOnly を使用すると、CacheSelector で定義されたキャッシュのすべての書き込みデータプレーン API にアクセスできるようになります。 CacheRole.WriteOnly は、SetIfNotExists のような条件付きの書き込みを意味する API や、ListPushBack が新しい長さを返すなど、コレクションの更新状態に関する情報を返す API には使用できません。カスタムロールはサポートされていません。

キャッシュの場合、値は組み込みの AllCaches か、このパーミッションのキャッシュ名を含む文字列となります。

item の場合、値は組み込みの AllCacheItems か、このパーミッションが対象とするキャッシュアイテムのキーまたはキープレフィックスを含む文字列となります。

DisposableTokenScope オブジェクトの例

これは、3 種類のパーミッション・オブジェクトをすべて持つ DisposableTokenScope を作成する例です： CachePermission、TopicPermission、DisposableTokenCachePermission です。

const exampleDisposableTokenPermission: DisposableTokenCachePermission = {
  role: CacheRole.WriteOnly,
  cache: "WriteCache",
  item: {
    keyPrefix: "WriteKey"
  }
};

const exampleCachePermission: CachePermission = {
  role: CacheRole.ReadOnly,
  cache: "ReadCache"
};

const exampleTopicPermission: TopicPermission = {
  role: TopicRole.PublishSubscribe,
  cache: "ReadWriteCache",
  topic: "MyTopic"
}

const exampleScope: DisposableTokenScope = {
    permissions: [
      exampleDisposableTokenPermission,
      exampleCachePermission,
      exampleTopicPermission,
    ],
};

// Then pass in the entire DisposableTokenScope object when
// you call generateDisposableToken
const tokenResponse = await authClient.generateDisposableToken(
  exampleScope,
  ExpiresIn.minutes(30)
);

FAQ

キャッシュやトピックのパーミッションにカスタムロールを作成できますか?

各権限について、上記の管理された役割のみをサポートしています。

これらのトークンは、MomentoのコントロールプレーンAPIへのアクセスを制御しますか？

GenerateAuthTokenAPIで生成されたアクセストークンは、MomentoのデータプレーンAPIへのアクセスのみを制御します。Momento のコントロールプレーン API にアクセスするためのトークンは、Momento console を使用して生成する必要があります。

ヒント

ここで答えられない質問があれば、私たちのDiscordサーバーに飛び、サポートチャンネルで私たちに質問してください。