Cognito API ハンズオン > Cognito Identity Provider API > ハンズオン内容の解説

ハンズオン内容の解説

Cognito Identity Provider API と API Gateway で用意した REST API を以下の流れで呼び出していきます。

Cognito Identity Provider API の利用する API は 4 つとも非 Admin API と分類できる API で、通常はモバイルアプリや SPA (Single Page Application) から直接呼び出して使う API です。本ハンズオンでは、API の理解がしやすいように Postman あるいは curl コマンドを利用します。

指定したユーザプールにユーザ登録を行う API です。SignUp は IAM による認証を使用しない API で、ブラウザやモバイルアプリからユーザ認証される前に呼び出される想定の API となっています。

API へのパラメータは、HTTP のリクエストボディに JSON 形式で主に以下の内容を入れて送ります。

{
   "ClientId": "string",
   "SecretHash": "string",
   "Username": "string",
   "Password": "string"
}

ClientId は Cognito ユーザプールに登録したアプリクライアントの ID です。アプリクライアントシークレットが設定されている Confidential クライアントの場合は SecretHash の指定が必要ですが、シークレットが設定されていない Public クライアントの場合は SecretHash は省略します。

実際には他にもいくつかパラメータがあるため、詳しくは API リファレンス - SignUp を確認ください。

2. ユーザ登録確認 (ConfrmSignUp)

SignUp で登録したユーザはまだ仮登録状態で、まだサインインは行うことができません。ユーザプールの設定によりますが、ユーザ自身がメールや SMS で受け取った確認コードを本 API で送るか、管理者が確認操作 (AdminConfirmSignUp) を行う必要があります。SignUp も IAM による認証を使用しない API です。API へのパラメータは主に以下の内容を入れて送ります。

{
   "ClientId": "string",
   "SecretHash": "string",
   "Username": "string",
   "ConfirmationCode": "string"
}

ClientId、SecretHash は SignUp と同じで、Confidential クライアントの場合のみ SecretHash が必要です。

こちらも実際には他にもいくつかパラメータがあるため、詳しくは API リファレンス - ConfrmSignUp を確認ください。

3. ユーザ認証 (InitiateAuth)

ユーザ認証を行う API です。使用する認証フロー、認証に MFA を利用するかどうかで、大きく API の利用方法が変わります。ユーザ認証が 1 回の API 呼び出しで完了せず、追加で RespondToAuthChallenge API を呼び出さないといけないケースがあります。本ハンズオンでは簡単に呼び出せる認証フロー USER_PASSWORD_AUTH を MFA 設定していないユーザで認証させるため、InitiateAuth の 1 回呼び出しで完結します。

InitiateAuth も IAM による認証を使用しない API で、USER_PASSWORD_AUTH を使う場合の API へのパラメータは主に以下の内容を入れて送ります。

{
   "ClientId": "string",
   "AuthFlow": "USER_PASSWORD_AUTH",
   "AuthParameters": { 
      "USERNAME" : "string",
      "PASSWORD" : "string"
    }
}

他の認証フローを使う場合は場合は、AuthFlow で認証フローを指定した上で、認証フローに応じた AuthParameters を入力する必要があります。詳しくは API リファレンス - InitiateAuth, API リファレンス - RespondToAuthChallenge を確認ください。

API の呼び出しに成功した場合は、結果としておおよそ以下のような結果が返ってきます。

{
    "AuthenticationResult": {
        "AccessToken": "??????????",
        "IdToken": "??????????",
        "RefreshToken": "??????????",
        "TokenType": "Bearer",
        "ExpiresIn": 3600
    },
    "ChallengeParameters": {}
}

トークンとしては、多くの場合 AccessToken、IdToken、RefreshToken の 3 種類が返ってきます。それぞれはヘッダ、ペイロード、署名の 3 つが含まれており、それぞれが BASE64 でエンコードされ、”.” (ピリオド) で連結されています。AccessToken、IdToken のペイロードは JSON 形式となっており、認証情報の内容が確認できます。

InitiateAuth の 1 回の呼び出しで認証が完結せず、追加で RespondToAuthChallenge API を呼び出して送るべき情報がある場合は、 ChallengeParameters で内容が指定されます。

4. REST API アクセス (API Gateway)

2. AWS サービスの準備で API Gateway を使って作成した REST API にアクセスします。

API には Cognito オーソライザーが設定されているため、InitiateAuth 呼び出しで得られた ID トークンを Authorization ヘッダの値として送る必要があります。

5. ユーザ削除 (DeleteUser)

ユーザを削除する API です。ユーザが認証してトークンを得た後に、ユーザ自身が登録を削除する API となっています。

DeleteUser も IAM による認証を使用しない API ですが、ユーザ認証時に得たトークンを API へのパラメータに入れて API を呼び出します。ユーザ自身を削除する前提の API のため、ユーザ名などのパラメータはありません。

{
   "AccessToken": "string"
}

API 共通

Cognito Identity Provider API のエンドポイントは以下の URL です。

https://cognito-idp.<region>.amazonaws.com/

ハンズオンで利用する 4 つの API では、API のパラメータを HTTP リクエストボディに JSON 形式で入れて呼び出しますが、加えて HTTP リクエストヘッダで以下の項目も最低限指定が必要です。

ヘッダ項目	値
Content-Type	application/x-amz-json-1.1
X-Amz-Target	AWSCognitoIdentityProviderService.<呼び出すAPI名>