カスタム JWT 認証

認証と承認

サードパーティの JWT プロバイダーはユーザーを認証し、JWT を返します。Atlas App Services は JWT を使用して、アプリケーションのユーザーを識別し、そのリクエストを承認します。

Atlas App Services は、サードパーティ プロバイダーが使用する認証方法には依存しません。外部認証システムの要件や認証方法に制限が加えられることはありません。たとえば、システムより、ユーザが多要素認証（MFA）を実行すること、特定の認証情報を提供すること、またはその他の方法で自分自身を識別することを要求できます。

JWT 認証の仕組み

JWT 認証の複雑さとトークン構造を詳しく説明する多くのオンライン リソースがあります。以下の図は、Atlas App Services のコンテキストにおける、Device Sync アプリにログオンするユーザーのプロセス フローを示したものです。図の下にある手順で、詳細を説明しています。

クリックして拡大します

Atlas App Services を使用した JWT 認証は、次の一般的な手順に従います。

1. ユーザは、プロバイダーが要求する手段を用いて、サード パーティ認証プロバイダーにログオンします。

2. 認証が成功すると、プロバイダーはクライアント アプリに JWT を返します。

3. クライアント アプリは App Services アプリにログオンし、JWT 認証情報を提供します。

4. App Services は JWT を解析してデコードします。

5. Atlas App Services で署名キーを手動で指定した場合、Atlas App Services は、JWT の署名キーが指定した署名キーのいずれかと一致するかどうかを確認します。その場合、ユーザーが認証されます。

6. JSON Web キー（JWK）URI を使用するように Atlas App Services を設定した場合、Atlas App Services は JWT と公開キーをサードパーティ プロバイダーの JWK API に渡します。

   1. プロバイダーは署名をデコードして検証し、JWK を返します。

   2. Atlas App Services は、JWK にある署名が JWT の署名と一致するかどうかを確認します。その場合、ユーザーが認証されます。

構成

カスタム JWT 認証は、UI または CLI を使用して構成します。以下から希望する方法を選択します。

{
  "custom-token": {
    "name": "custom-token",
    "type": "custom-token",
    "config": {
      "audience": "<JWT Audience>",
      "requireAnyAudience": <boolean>,
      "signingAlgorithm": "<JWT Signing Algorithm>",
      "useJWKURI": <boolean>,
      "jwkURI": "<JWK or JWKS URL>",
    },
    "secret_config": {
      "signingKeys": [
        "<Signing Key Secret Name>",
        ...
      ]
    },
    "metadata_fields": [
      {
        "required": <boolean>,
        "name": "<JWT Field Path>",
        "field_name": "<Metadata Field Name>",
      },
      ...
    ],
    "disabled": <boolean>
  }
}

検証方法

[Verification Method] フィールドは、JWT プロバイダーから返された JWT を Atlas App Services が検証する方法を決定します。提供した署名キーを使用して JWT を検証するか、またはサードパーティ プロバイダーによって発行された JSON Web Ke (JWK) URI を使用して検証するように Atlas App Services を設定できます。

署名キーの手動指定

1 つ以上の署名キーを使用して、JWT を検証するようにアプリを構成できます。次の 2 つの設定を指定する必要があります。

フィールド	説明
Signing Algorithm config.signingAlgorithm	外部システムが JWT に署名するために使用する暗号化方法。カスタム認証では、次のいずれかのアルゴリズムを使用して署名された JWT がサポートされます。 HS256 RS256
Signing Key secret_config.signingKeys	サードパーティの認証システムにより、 JWT に署名するために使用される署名キーをそれぞれが含んでいる最大 3つの Secret のリスト。キーは ASCII 文字、数字、アンダースコア、ハイフンのみで、32 文字以上 512 文字以下でなければなりません。以下は、有効な 256 ビットの署名キーです。 231a58b00632c9c4d8ac02b268ca4caf8dd48fd020e3dffa72666523d860988f 注意 どのような値を使用すればよいかわからない場合は、keygen.ioなどのランダムなキー ジェネレーターのウェブサイトにアクセスするか、256 ビット値の 1 つを使用することを検討してください。

アプリ サービス UI

Atlas App Services CLI

1. 署名アルゴリズムを設定します。

   

2. JWT に署名するための 1 つ以上の署名キーを作成します。そのためには、鍵の名前を指定し（後で参照するだけのものです）、256 ビットの署名鍵を指定します。

   

"config": {
  "signingAlgorithm": "<JWT Signing Algorithm>",
},
"secret_config": {
  "signingKeys": [
    "<Signing Key Secret Name>",
    ...
  ]
}

警告

Signing Key は秘密キーで、このキーを持つユーザーは誰でもアプリの有効なユーザー認証情報を発行できます。Git リポジトリやメッセージボード、コード内など、一般にアクセス可能なロケーションには絶対に保存しないようにしてください。

Use a JWK URI

一部の外部認証システムは JSON Web Key Set （JWKS）を提供しています。これは、システムが JWT に署名するために使用する署名アルゴリズムと署名キーを記述します。署名アルゴリズムとキーを手動で指定する代わりに、JWKS を使用してプロバイダーを構成できます。返される JWKS には、JWKS のキーのキー ID を指定する kid ヘッダーが含まれている必要があります。JWKS は最大 3 つの署名キーを指定でき、RS256 アルゴリズムを使用する必要があります。

注意

Atlas App Services では、JWK と JWKS は同義として使用されます。

指定する必要がある値は 1 つだけです。

• JWK URIこれは、JWK または JWKS サービスをホストするサードパーティの URL です。このオプションを選択すると、App Service は暗号化を必要な RS256 方式に自動的に設定します。

アプリ サービス UI

Atlas App Services CLI

サードパーティの JWKS エンドポイントへの URL を指定します。

"config": {
  "useJWKURI": <boolean>,
  "jwkURI": "<JWK or JWKS URL>"
}

メタデータ フィールド

Metadata Fields 各内部 App Services ユーザーを説明する追加データです。App Services は、サードパーティの JWT に含まれるフィールドの値から、各メタデータ フィールドの値を決定します。たとえば、ユーザーの name フィールドを設定すると、Atlas App Services は JWT 内のそのフィールドをユーザーの表示名として使用します。

注意

App Services は、ユーザーがログインするたびにユーザーのメタデータを更新し、ユーザー メタデータの data オブジェクトのフィールドを公開します。

重要

JWT とメタデータ フィールドの文字制限

JWT トークンの文字数は、トークン内のメタデータ フィールドの数と各フィールドのサイズに応じて増加します。App Services では、JWT トークンの文字数が 1,000,000 字に、各メタデータ フィールドの文字数が 4096 字に制限されます。文字数制限を超えると、App Services によってエラーがログに記録され、チケットは処理されません。

各メタデータ フィールドには、次の 3 つの値を指定する必要があります。

フィールド	説明
Required required	true の場合、プロバイダーに関連付けられているすべてのユーザーにメタデータ フィールドが必要になります。外部システムから返される JWT には、Path で指定されたフィールドに割り当てられている値が必要です。
Path name	メタデータ フィールドの値を含む JWT 内のフィールドの名前またはパス。埋め込みオブジェクト内のフィールドへのパスを指定するには、ドット表記を使用します。JWT 内のフィールド名自体にピリオド（ .）文字が含まれている場合は、バックスラッシュ（ \）を使用してピリオドをエスケープします。たとえば、名前が http://example.com/idの場合は、http://example\.com/id を使用します。
Field Name field_name	任意。JWT パス にマップされるユーザー オブジェクトの dataドキュメント内のメタデータ フィールドの名前。このフィールド名の長さは 64 文字未満にする必要があります。 デフォルト値のルール このフィールドが指定されていない場合、名前は値を含む JWT フィールドの名前にデフォルト設定されます。 このフィールドが指定されておらず、Path 値がドット表記を使用している場合、デフォルトの名前は表記の最後の部分になります。たとえば、パスを location.primary.city に指定した場合、名前のデフォルト値は city になります。

アプリ サービス UI

Atlas App Services CLI

メタデータ フィールドを定義するには、[Add Field] をクリックし、JWT 内のメタデータ フィールドとユーザー オブジェクト内の対応するフィールド名とのマッピングを指定します。

カスタム JWT 認証構成ファイルでメタデータ フィールドを定義するには、フィールドのエントリを metadata_fields 配列に追加します。各エントリは、以下の形式のドキュメントでなければなりません。

{
  required: <boolean>,
  name: "<field path>",
  field_name: "<metadata field name>"
}

JWT キー内のピリオド（ .）文字をエスケープするには、バックスラッシュ（ \）を使用します。

たとえば、この JSON オブジェクトでは、パス名の"nested_key"をvalid\.json\.key\.nested_keyとして表します。

{ "valid.json.key": {
    "nested_key": "val"
  }
}

例

外部認証システムは、user_data フィールドに各ユーザーに関する追加情報を含む JWT を返します。

(JWT JSON)
{
  "aud": "myapp-abcde",
  "exp": 1516239022,
  "sub": "24601",
  "user_data": {
    "name": "Jean Valjean",
    "aliases": [
      "Monsieur Madeleine",
      "Ultime Fauchelevent",
      "Urbain Fabre"
    ]
  }
}

各ユーザーのユーザー オブジェクトに user_data フィールドの値を含めるには、App Services 構成で次のメタデータ フィールドを指定します。

パス	フィールド名
user_data.name	name
user_data.aliases	aliases

ユーザー オブジェクトには、次のフィールドが含まれるようになりました。

(USER METADATA OBJECT)
{
  "id": "59fdd02846244cdse5369ebf",
  "type": "normal",
  "data": {
    "name": "Jean Valjean",
    "aliases": [
      "Monsieur Madeleine",
      "Ultime Fauchelevent",
      "Urbain Fabre"
    ]
  },
  identities: [
    {
      "id": "24601",
      "provider_type": "custom-token",
      "data": {
        "name": "Jean Valjean",
        "aliases": [
          "Monsieur Madeleine",
          "Ultime Fauchelevent",
          "Urbain Fabre"
        ]
      },
    }
  ]
}

オーディエンス

JWTの Audience は、トークンの対象受信者を指定します。JWT は、 aud のクレームでオーディエンスを記述します。App Services では、aud にプロバイダーが構成されているアプリのアプリ ID が含まれていることを想定しています。ただし、外部認証システム JWT で別の aud 値が指定されている場合は、代わりにその値を使用するようにプロバイダーを構成できます。

アプリ サービス UI

Atlas App Services CLI

次の 2 つのフィールドを設定します。

フィールド	説明
Audience	クライアント JWT に含まれることが期待されるオーディエンスの単一の値、またはカンマ区切りの値のリスト。
Require	複数のオーディエンスを指定する場合、それらの処理方法を指定する必要があります。選択肢は次のとおりです。 これらすべてのオーディエンス: JWT にはリスト内のすべてのオーディエンスを含める必要があります。 これらのオーディエンスのいずれか: JWT には、リストから 1 つのオーディエンスを含めるだけです。

オーディエンスを設定するには、 config.audience を設定します。次の 2 つのフィールドを設定します。

フィールド	説明
audience	クライアント JWT に含まれていると予想されるオーディエンスを指定する文字列の配列。
requireAnyAudience	ブール値。false の場合、JWT にはリストされているすべてのオーディエンスを含める必要があります。true の場合、JWT にはもっぱらリストされているオーディエンスの 1 つ以上を含める必要があります。

"config": {
  "audience": [
    "<JWT Audience>",
  ],
  "requireAnyAudience": <boolean>,
}

JWT 認証の使用

新しいカスタム JSON web token ユーザーを登録し、Realm SDK または API サービスのいずれかを使用してログできます。