Oracle Cloud Infrastructureドキュメント

アイデンティティ・ドメインでのDuo Securityの使用

これらのユースケースでは、アイデンティティ・ドメインでDuo Web SDK v2またはDuo Web SDK v4を使用するステップバイステップの例を示します。

Duoセキュリティ設定を使用した認証ファクタ設定の更新

次の例では、cURLを使用してRESTリソースに対するPUTリクエストを発行することによって、テナントの多要素認証設定を更新する方法を示しています。cURLの詳細は、「cURLの使用」を参照してください。

cURLコマンド

ノート

この例のコマンドでは、URL構造https://<domainURL>/resource-pathを使用しています。この<domainURL>はIdentity Service URLを示し、リソース・パスはIdentity Service APIを表しています。使用する適切なURL構造の詳細は、「リクエストの送信」を参照してください。
   curl
-X PUT
   -H "Content-Type:application/scim+json"
   -H "Authorization: Bearer <Access Token Value>"
https://<domainURL>/admin/v1/AuthenticationFactorSettings/<ID>

リクエスト本体

JSON形式のリクエスト本文の例を次に示します:
リクエスト本文の例
{
  "bypassCodeSettings": {
    "helpDeskCodeExpiryInMins": 60,
    "helpDeskGenerationEnabled": true,
    "helpDeskMaxUsage": 5,
    "length": 12,
    "maxActive": 5,
    "selfServiceGenerationEnabled": true
  },
  "clientAppSettings": {
    "deviceProtectionPolicy": "NONE",
    "initialLockoutPeriodInSecs": 30,
    "keyPairLength": 2048,
    "lockoutEscalationPattern": "Constant",
    "maxFailuresBeforeLockout": 10,
    "maxFailuresBeforeWarning": 5,
    "maxLockoutIntervalInSecs": 86400,
    "minPinLength": 6,
    "policyUpdateFreqInDays": 7,
    "requestSigningAlgo": "SHA256withRSA",
    "sharedSecretEncoding": "Base32",
    "unlockAppForEachRequestEnabled": false,
    "unlockAppIntervalInSecs": 300,
    "unlockOnAppForegroundEnabled": false,
    "unlockOnAppStartEnabled": false
  },
  "compliancePolicy": [
    {
      "action": "Allow",
      "name": "lockScreenRequired",
      "value": "false"
    },
    {
      "action": "Allow",
      "name": "lockScreenRequiredUnknown",
      "value": "false"
    },
    {
      "action": "Allow",
      "name": "jailBrokenDevice",
      "value": "false"
    },
    {
      "action": "Allow",
      "name": "jailBrokenDeviceUnknown",
      "value": "false"
    },
    {
      "action": "Allow",
      "name": "minWindowsVersion",
      "value": "8.1"
    },
    {
      "action": "Allow",
      "name": "minIosVersion",
      "value": "7.1"
    },
    {
      "action": "Allow",
      "name": "minAndroidVersion",
      "value": "4.1"
    },
    {
      "action": "Allow",
      "name": "minIosAppVersion",
      "value": "4.0"
    },
    {
      "action": "Allow",
      "name": "minAndroidAppVersion",
      "value": "8.0"
    },
    {
      "action": "Allow",
      "name": "minWindowsAppVersion",
      "value": "1.0"
    }
  ],
  "endpointRestrictions": {
    "maxEndpointTrustDurationInDays": 15,
    "maxEnrolledDevices": 5,
    "maxTrustedEndpoints": 5,
    "trustedEndpointsEnabled": true,
    "maxIncorrectAttempts": 10
  },
  "id": "AuthenticationFactorSettings",
  "mfaEnrollmentType": "Required",
  "pushEnabled": false,
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorSettings"
  ],
  "thirdPartyFactor": {
        "duoSecurity": true
    },
  "notificationSettings": {
        "pullEnabled": true
    },
     "urn:ietf:params:scim:schemas:oracle:idcs:extension:thirdParty:AuthenticationFactorSettings": {
        "duoSecuritySettings": {
            "integrationKey": "XXXXXXXXXXXXXXXXXXXX",
            "secretKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "apiHostname": "api-example.duosecurity.com",
            "userMappingAttribute": "userName"
    }
    },
  "securityQuestionsEnabled": false,
  "smsEnabled": false,
  "emailEnabled": false,
  "bypassCodeEnabled": false,
  "totpEnabled": false,
  "totpSettings": {
    "hashingAlgorithm": "SHA1",
    "jwtValidityDurationInSecs": 300,
    "keyRefreshIntervalInDays": 60,
    "passcodeLength": 6,
    "smsOtpValidityDurationInMins": 10,
    "smsPasscodeLength": 6,
    "timeStepInSecs": 30,
    "timeStepTolerance": 3,
	"emailOtpValidityDurationInMins": 10,
	"emailPasscodeLength": 6
  },
  "mfaEnabledCategory": "NONE"
}

レスポンス本文

次の例に、レスポンスボディーの内容を JSON形式で示します。

レスポンス本文の例
{
    "bypassCodeSettings": {
        "helpDeskCodeExpiryInMins": 60,
        "helpDeskGenerationEnabled": true,
        "helpDeskMaxUsage": 5,
        "length": 12,
        "maxActive": 5,
        "selfServiceGenerationEnabled": true
    },
    "clientAppSettings": {
        "deviceProtectionPolicy": "NONE",
        "initialLockoutPeriodInSecs": 30,
        "keyPairLength": 2048,
        "lockoutEscalationPattern": "Constant",
        "maxFailuresBeforeLockout": 10,
        "maxFailuresBeforeWarning": 5,
        "maxLockoutIntervalInSecs": 86400,
        "minPinLength": 6,
        "policyUpdateFreqInDays": 7,
        "requestSigningAlgo": "SHA256withRSA",
        "sharedSecretEncoding": "Base32",
        "unlockAppForEachRequestEnabled": false,
        "unlockAppIntervalInSecs": 300,
        "unlockOnAppForegroundEnabled": false,
        "unlockOnAppStartEnabled": false
    },
    "compliancePolicy": [
        {
            "action": "Allow",
            "name": "lockScreenRequired",
            "value": "false"
        },
        {
            "action": "Allow",
            "name": "lockScreenRequiredUnknown",
            "value": "false"
        },
        {
            "action": "Allow",
            "name": "jailBrokenDevice",
            "value": "false"
        },
        {
            "action": "Allow",
            "name": "jailBrokenDeviceUnknown",
            "value": "false"
        },
        {
            "action": "Allow",
            "name": "minWindowsVersion",
            "value": "8.1"
        },
        {
            "action": "Allow",
            "name": "minIosVersion",
            "value": "7.1"
        },
        {
            "action": "Allow",
            "name": "minAndroidVersion",
            "value": "4.1"
        },
        {
            "action": "Allow",
            "name": "minIosAppVersion",
            "value": "4.0"
        },
        {
            "action": "Allow",
            "name": "minAndroidAppVersion",
            "value": "8.0"
        },
        {
            "action": "Allow",
            "name": "minWindowsAppVersion",
            "value": "1.0"
        }
    ],
    "endpointRestrictions": {
        "maxEndpointTrustDurationInDays": 15,
        "maxEnrolledDevices": 5,
        "maxTrustedEndpoints": 5,
        "trustedEndpointsEnabled": true,
        "maxIncorrectAttempts": 10
    },
    "id": "AuthenticationFactorSettings",
    "mfaEnrollmentType": "Required",
    "pushEnabled": false,
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorSettings"
    ],
    "thirdPartyFactor": {
        "duoSecurity": true
    },
    "notificationSettings": {
        "pullEnabled": true
    },
    "urn:ietf:params:scim:schemas:oracle:idcs:extension:thirdParty:AuthenticationFactorSettings": {
        "duoSecuritySettings": {
            "integrationKey": "XXXXXXXXXXXXXXXXXXXX",
            "secretKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "apiHostname": "api-example.duosecurity.com",
            "userMappingAttribute": "userName"
        }
    },
    "securityQuestionsEnabled": false,
    "smsEnabled": false,
    "emailEnabled": false,
    "bypassCodeEnabled": false,
    "totpEnabled": false,
    "totpSettings": {
        "hashingAlgorithm": "SHA1",
        "jwtValidityDurationInSecs": 300,
        "keyRefreshIntervalInDays": 60,
        "passcodeLength": 6,
        "smsOtpValidityDurationInMins": 10,
        "smsPasscodeLength": 6,
        "timeStepInSecs": 30,
        "timeStepTolerance": 3,
        "emailOtpValidityDurationInMins": 10,
        "emailPasscodeLength": 6
    },
    "meta": {
        "lastModified": "2022-10-15T07:44:53.601Z",
        "resourceType": "AuthenticationFactorSettings",
        "created": "2022-10-04T06:56:10.285Z",
        "location": "https://<domainURL>/admin/v1/AuthenticationFactorSettings/AuthenticationFactorSettings"
    },
    "idcsLastModifiedBy": {
        "value": "5753639d3ca046f094a8f4aeaf9ea5e5",
        "type": "App",
        "display": "testPostman",
        "$ref": "https://<domainURL>/admin/v1/Apps/5753639d3ca046f094a8f4aeaf9ea5e5"
    },
    "idcsCreatedBy": {
        "value": "c480fd39014e40f3bf4f963b3b6a423b",
        "type": "App",
        "display": "idcssm",
        "$ref": "https://<domainURL>/admin/v1/Apps/c480fd39014e40f3bf4f963b3b6a423b"
    },
    "mfaEnabledCategory": "NONE"
}

Duo Web SDKの有効化 v4

Duo Web SDK v2 (iFrame)は、アイデンティティ・ドメインでデフォルトで有効になっています。Duo Web SDK v4を使用するには、有効にする必要があります。

Duo Web SDK v4を有効にするには、次の手順を使用します。

  1. cURLの使用、GET /admin/v1/AuthenticationFactorSettings/AuthenticationFactorSettings

    レスポンスの例

    次のDuo Web SDKのv2設定が表示されます。

    "urn:ietf:params:scim:schemas:oracle:idcs:extension:thirdParty:AuthenticationFactorSettings": {
   "duoSecuritySettings": {
      "integrationKey": "<integration-key>",
      "secretKey": "<secret-key>",
      "apiHostname": "api-example.duosecurity.com",
      "userMappingAttribute": "userName"
}
  2. ロールバックが必要な場合に備えてインスタンスをバックアップします。

  3. urn:ietf:params:scim:schemas:oracle:idcs:extension:thirdParty:AuthenticationFactorSettingsセクションの下にenableWebSDKv4およびduoSecurityAuthzRedirectUrlを追加して、ステップ1のペイロードを更新します。

    • enableWebSDKv4: デフォルト値はfalseです。enableWebSDKv4がfalseの場合、Duo Web SDK v2が使用されます。

    • duoSecurityAuthzRedirectUrl: デフォルト値は空白です。ここに組織のURLを追加します。リダイレクトURLは、Duoセキュリティ認証を開始するために使用されます。Duoセキュリティ・サーバーは、duoSecurityAuthzStateおよびduoSecurityAuthzCodeを使用してDuoセキュリティ・サーバーからレスポンスを受け取ります。このURLは、カスタムUIを使用して上書きできます。カスタムUIは、このエンドポイントを使用して、Duoセキュリティ・サーバーからコードとパラメータを受信する必要があります。

    次の属性がv2からv4に変更されることに注意してください。

    • client_id (v2のintegrationKey)
    • clientSecret (v2のsecretKey)
    • apiHostName (v2からの変更なし)
    • userMappingAttribute (v2からの変更なし)

    リクエストの例

    "urn:ietf:params:scim:schemas:oracle:idcs:extension:thirdParty:AuthenticationFactorSettings": {
   "duoSecuritySettings": {
       "integrationKey": "<integration-key>",
       "secretKey": ""<secret-key>"",
       "apiHostname": "api-6ff7f509.duosecurity.com",
       "userMappingAttribute": "primaryEmail",
       "enableWebSDKv4": true,
       "duoSecurityAuthzRedirectUrl": "https://abc.co/a/c"
   }
}

  4. ステップ3のペイロードを使用したcURL、PUT /admin/v1/AuthenticationFactorSettings/AuthenticationFactorSettingsの使用。

認証ファクタとしてDuoセキュリティを使用したユーザー名およびパスワードの認証

このユースケースでは、アイデンティティ・ドメインREST APIを使用してユーザーを認証し、Duo Web SDK v2またはDuo Web SDK v4でマルチファクタの登録および認証を実行するステップバイステップの例を示します。

ノート

  • この認証APIを使用するのは、アイデンティティ・ドメインで使用するカスタム・サインイン・アプリケーションを開発して、独自のエンドツーエンド・ログイン・エクスペリエンスを構築する場合のみです。
  • この認証APIを使用して、シングル・サインオンのためにアプリケーションをアイデンティティ・ドメインと統合することはできません。
ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。

このユースケースには、次の例のセットが含まれています:

Web SDK v2を使用したDuoセキュリティでの新規ユーザーの登録

このユースケースでは、アイデンティティ・ドメインREST APIを使用して新規ユーザーおよび関連デバイスをDuo Web SDK v2に登録するステップ・バイ・ステップの例を示します。

ノート

  • この認証APIを使用するのは、アイデンティティ・ドメインで使用するカスタム・サインイン・アプリケーションを開発して、独自のエンドツーエンド・ログイン・エクスペリエンスを構築する場合のみです。
  • この認証APIを使用して、シングル・サインオンのためにアプリケーションをアイデンティティ・ドメインと統合することはできません。
ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。

この使用例では、次のステップを使用します。各ステップには、リクエストおよびレスポンスの例が含まれます:

ノート

これらのステップでは、MFAが有効であり、MFAのサインオン・ポリシーが作成されていることを前提としています。「多要素認証設定の構成」を参照してください。

ステップ1: 認証フローの開始

最初のrequestStateを取得して、認証フローを開始します。

リクエストの例

cURL形式のリクエストの例を次に示します: 

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}
ノート

appNameはオプションです。appNameは、クライアントがアクセスするアプリケーションの名前です。appNameを指定すると、アプリケーションに固有のサインオン・ポリシーが処理され、クライアントは、そのポリシーに基づいて必要なファクタのチャレンジを受けます。

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ2: ユーザーの資格証明の発行

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "4uy3^1k0000000000",
    "nextAuthFactors": [
        "TOTP",
        "SECURITY_QUESTIONS",
        "DUO_SECURITY",
        "SMS",
        "EMAIL",
        "PUSH"
    ],
    "EnrolledAccountRecoveryFactorsDetails": {
        "EMAIL": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "displayName": "clarence.saladna@example.com"
                }
            ]
        },
        "enrolledAccRecFactorsList": [
            "EMAIL"
        ]
    },
    "TOTP": {
        "credentials": [
            "offlineTotp"
        ]
    },
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "scenario": "ENROLLMENT",
    "requestState": "{{requestState}}"
}

このユースケースの例では、ユーザーの登録を開始するために、次のステップに送信されます。

ステップ3: Duoセキュリティ登録リクエストの開始

このステップでは、デュオ・セキュリティ登録を開始します。クライアントには次の属性が含まれている必要があります:

  • op: クライアントが必要とする操作の種類をサーバーに指示します
  • authFactor: ユーザーが登録する認証ファクタを定義します
  • requestState: ステップ2のレスポンスで受信

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
    "op": "enrollment",
    "authFactor": "DUO_SECURITY",
    "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のリクエストのコンテンツの例を次に示します:

{
   "status": "success",
   "ecId": "4uy3^1k0000000000",
   "DUO_SECURITY": {
      "credentials": [
         "duoSecurityResponse"
      ],
      "authnDetails": {
         "duoSecurityChallenge": "TX
          |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjMwNTM=
          |5853cc561ded98c72426b633a1b1e719401e2345:APP
          |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjYzNTM=
          |37f594101a380ff3902e0a2cb545346ed196bbca",
         "duoSecurityHost": "api-example.duosecurity.com"
      }
   },
   "nextOp": [
       "credSubmit",
       "createToken",
       "createSession",
       "enrollment"
   ],
   "mfaSettings": {
       "enrollmentRequired": false
   },
   "scenario": "ENROLLMENT",
   "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitが送信されます。

ステップ4: Duoセキュリティ認証の開始

DuoのWeb SDK v2を使用して、アイデンティティ・ドメインをDuoセキュリティと統合します。Duoは、セカンダリ認証に使用されるiFrameと対話するJavaScriptライブラリを提供します。

プライマリ認証の後、アイデンティティ・ドメインから受信したduoSecurityHostやduoSecurityChallengeなどの認証の詳細をiFrameに渡する必要があります。次の例を使用してDuoセキュリティ認証を開始し、iFrameをロードしてDuoセキュリティ・サーバーと接続できます。

function duo(msg, duoSecurityCallback) {
    Duo.init({iframe: "duo_iframe",
            host: msg.DUO_SECURITY.authnDetails.duoSecurityHost,
            sig_request: msg.DUO_SECURITY.authnDetails.duoSecurityChallenge,
            submit_callback: duoSecurityCallback,
            post_argument: "resp"
    });
}

Duo認証プロセスの完了後、DuoはduoSecurityCallbackメソッドをコールしてDuoレスポンスを取得します。

var duoSecurityCallback = function(details, credentials) {
       var credentials = {};
       credentials.duoSecurityResponse = details.firstElementChild.value;
       operation = "credSubmit";
       initiateAuth(credentials); 
}

Duoセキュリティのレスポンスを受信したら、レスポンスをアイデンティティ・ドメインに渡して認証を完了する必要があります。

ステップ5: ファクタ資格証明の発行

このステップでは、ステップ3のレスポンスで受信したrequestStateのファクタ資格証明を発行します。authFactor属性はrequestStateに含まれるため、リクエスト・ペイロードには含まれないことに注意してください。クライアントには次の属性が含まれている必要があります:

  • op: クライアントが必要とする操作の種類をサーバーに指示します
  • requestState: ステップ3のレスポンスで受信

リクエストの例

次の例に、ファクタ資格証明を発行するためのJSON形式のPOSTリクエストのコンテンツを示します:

{  
   "op":"credSubmit",
   "credentials": {  
       "duoSecurityResponse": "AUTH
      |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjM5NjA=
      |f2d0df2a189219a8e85db190ac66fab33be996c3:APP
      |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1Njc0NTU=
      |a3b7c901e845ebd80451ab670473e983707a8459"
   },
   "requestState":"{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "4uy3^1k0000000000",
    "displayName": "{{username}}'s Duo Security Account",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "scenario": "ENROLLMENT",
    "requestState": "{{requestState}}"
}

nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcreateTokenが送信されます。

ステップ6: 認証トークンの作成

このステップは、クライアントが完了し、セッションを作成する必要があることを示します。サーバーは、他のファクタ評価(ポリシーに定義されている内容に応じて)が必要ないことを検証し、トークンを使用して応答するか、アクセスを拒否します。クライアントには次の属性が含まれている必要があります:
  • op: クライアントが必要とする操作の種類をサーバーに指示します
  • requestState: ステップ5のレスポンスで受信

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{  
   "op":"createToken",
   "requestState":"{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{ "authnToken": "{{authnToken}}", "status": "success" }

Web SDK v4を使用したDuoセキュリティでの新規ユーザーの登録

このユースケースでは、アイデンティティ・ドメインREST APIを使用して新規ユーザーおよび関連デバイスをDuo Web SDK v4に登録するステップ・バイ・ステップの例を示します。

ノート

Duo Web SDK v4を有効にする必要がある場合は、Duo Web SDKの有効化 v4を参照してください。
ノート

  • この認証APIを使用するのは、アイデンティティ・ドメインで使用するカスタム・サインイン・アプリケーションを開発して、独自のエンドツーエンド・ログイン・エクスペリエンスを構築する場合のみです。
  • この認証APIを使用して、シングル・サインオンのためにアプリケーションをアイデンティティ・ドメインと統合することはできません。
ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。

この使用例では、次のステップを使用します。各ステップには、リクエストおよびレスポンスの例が含まれます:

ノート

これらのステップでは、MFAが有効であり、MFAのサインオン・ポリシーが作成されていることを前提としています。「多要素認証設定の構成」を参照してください。

ステップ1: 認証フローの開始

最初のrequestStateを取得して、認証フローを開始します。

リクエストの例

cURL形式のリクエストの例を次に示します: 

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}
ノート

appNameはオプションです。appNameは、クライアントがアクセスするアプリケーションの名前です。appNameを指定すると、アプリケーションに固有のサインオン・ポリシーが処理され、クライアントは、そのポリシーに基づいて必要なファクタのチャレンジを受けます。

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ2: ユーザーの資格証明の発行

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "4uy3^1k0000000000",
    "nextAuthFactors": [
        "TOTP",
        "SECURITY_QUESTIONS",
        "DUO_SECURITY",
        "SMS",
        "EMAIL",
        "PUSH"
    ],
    "EnrolledAccountRecoveryFactorsDetails": {
        "EMAIL": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "displayName": "clarence.saladna@example.com"
                }
            ]
        },
        "enrolledAccRecFactorsList": [
            "EMAIL"
        ]
    },
    "TOTP": {
        "credentials": [
            "offlineTotp"
        ]
    },
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "scenario": "ENROLLMENT",
    "requestState": "{{requestState}}"
}

このユースケースの例では、ユーザーの登録を開始するために、次のステップに送信されます。

ステップ3: Duoセキュリティ登録リクエストの開始

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
    "op": "enrollment",
    "authFactor": "DUO_SECURITY",
    "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のリクエストのコンテンツの例を次に示します。

{
   "status": "success",
   "ecId": "i2tul0R0000000000",
   "nextAuthFactors": [
      "DUO_SECURITY"
   ],
   "DUO_SECURITY": {
      "credentials": [
         "duoSecurityAuthzCode",
         "duoSecurityAuthzState"
      ],
      "authnDetails": {
         "duoSecurityAuthzRequest": "https://api-xxxxxxxx.duosecurity.com/oauth/v1/authorize?response_type=code&client_id=<client_id>&redirect_uri=duoSecurityAuthzRedirectURL&state=3047103d-d707-4b94-a960-203430071154&request=<request>"
      }
   },
   "nextOp": [
      "credSubmit",
      "getBackupFactors"
   ],
   "scenario": "AUTHENTICATION",
   "requestState": "requestState",
   "trustedDeviceSettings": {
      "trustDurationInDays": 15
   }
}

ステップ4: Duoセキュリティ認証の開始

Duoセキュリティ認証中、ブラウザはDuoセキュリティ・サーバーにリダイレクトされ、Duoセキュリティ・サーバーは、ユーザーがセカンダリ認証を実行するセカンダリ認証ページをロードします。認証に成功すると、Duoセキュリティ・サーバーは状態(duoSecurityAuthzState)およびコード(duoSecurityAuthzCode)パラメータで応答します。認証を完了するには、これらのパラメータをアイデンティティ・ドメインに送信する必要があります。

次のステップを使用して、状態およびコード・パラメータを取得します。

  1. duoSecurityAuthzRequestからリダイレクト先のURLを取得します。

    例: 
    "duoSecurityAuthzRequest": "https://api-xxxxxxxx.duosecurity.com/oauth/v1/authorize?response_type=code&client_id=<client_id>&redirect_uri=duoSecurityAuthzRedirectURL&state=3047103d-d707-4b94-a960-203430071154&request=<request>"

    duoSecurityAuthzRedirectURLのリダイレクトURLです。

  2. Do 303「Duo Security Server」にリダイレクトします。

  3. Duoセキュリティの登録および認証プロセスを完了します。

    Duoセキュリティ・サーバーは、duoSecurityAuthzStateおよびduoSecurityAuthzCodeを使用してduoSecurityAuthzRedirectURLにリダイレクトします。

ステップ5: ファクタ資格証明の発行

認証を完了するには、レスポンスからアイデンティティ・ドメインにduoSecurityAuthzStateおよびduoSecurityAuthzCodeを渡します。

リクエストの例

JSON形式のリクエストのコンテンツの例を次に示します:

{
    "op": "credSubmit",
    "credentials":
   {
      "duoSecurityAuthzCode": "<duo-security-authz-code>",
      "duoSecurityAuthzState": "<duo-security-authz-state>"
   }
,
    "requestState": "requestState"}'

レスポンスの例 

{
    "status": "success",
    "ecId": "4uy3^1k0000000000",
    "displayName": "{{username}}'s Duo Security Account",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "scenario": "ENROLLMENT",
    "requestState": "{{requestState}}"
}

ステップ6: 認証トークンの作成

このステップは、クライアントが完了し、セッションを作成する必要があることを示します。サーバーは、他のファクタ評価(ポリシーに定義されている内容に応じて)が必要ないことを検証し、トークンを使用して応答するか、アクセスを拒否します。クライアントには次の属性が含まれている必要があります:
  • op: クライアントが必要とする操作の種類をサーバーに指示します
  • requestState: ステップ5のレスポンスで受信

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{  
   "op":"createToken",
   "requestState":"{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{ "authnToken": "{{authnToken}}", "status": "success" }

Web SDK v2を使用したDuoセキュリティでのユーザー・アカウントの認証

このユースケースでは、アイデンティティ・ドメイン認証APIを使用して、Duo Web SDK v2でユーザー・アカウントを認証するステップ・バイ・ステップの例を示します。

ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。
この使用例では、次のステップを使用します。各ステップには、リクエストおよびレスポンスの例が含まれます:
ノート

これらのステップでは、MFAが有効であり、MFAのサインオン・ポリシーが作成されていることを前提としています。「多要素認証設定の構成」を参照してください

ステップ1: 認証フローの開始

最初のrequestStateを取得して、認証フローを開始します。

リクエストの例

cURL形式のリクエストの例を次に示します: 

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}
ノート

appNameはオプションです。appNameは、クライアントがアクセスするアプリケーションの名前です。appNameを指定すると、アプリケーションに固有のサインオン・ポリシーが処理され、クライアントは、そのポリシーに基づいて必要なファクタのチャレンジを受けます。

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ2: ユーザーの資格証明の発行

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "4uy3^1k0000000000",
    "nextAuthFactors": [
        "TOTP",
        "SECURITY_QUESTIONS",
        "DUO_SECURITY",
        "SMS",
        "EMAIL",
        "PUSH"
    ],
    "EnrolledAccountRecoveryFactorsDetails": {
        "EMAIL": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "displayName": "clarence.saladna@example.com"
                }
            ]
        },
        "enrolledAccRecFactorsList": [
            "EMAIL"
        ]
    },
    "TOTP": {
        "credentials": [
            "offlineTotp"
        ]
    },
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "scenario": "ENROLLMENT",
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitが送信されます。

ステップ3: Duoセキュリティ認証の開始

DuoのWeb SDK v2を使用して、アイデンティティ・ドメインをDuoセキュリティと統合します。Duoは、セカンダリ認証に使用されるiFrameと対話するJavaScriptライブラリを提供します。

プライマリ認証の後、アイデンティティ・ドメインから受信したduoSecurityHostやduoSecurityChallengeなどの認証の詳細をiFrameに渡する必要があります。次の例を使用してDuoセキュリティ認証を開始し、iFrameをロードしてDuoセキュリティ・サーバーと接続できます。

function duo(msg, duoSecurityCallback) {
    Duo.init({iframe: "duo_iframe",
            host: msg.DUO_SECURITY.authnDetails.duoSecurityHost,
            sig_request: msg.DUO_SECURITY.authnDetails.duoSecurityChallenge,
            submit_callback: duoSecurityCallback,
            post_argument: "resp"
    });
}

Duo認証プロセスの完了後、DuoはduoSecurityCallbackメソッドをコールしてDuoレスポンスを取得します。

var duoSecurityCallback = function(details, credentials) {
       var credentials = {};
       credentials.duoSecurityResponse = details.firstElementChild.value;
       operation = "credSubmit";
       initiateAuth(credentials); 
}

Duoセキュリティのレスポンスを受信したら、レスポンスをアイデンティティ・ドメインに渡して認証を完了する必要があります。

ステップ4: ファクタ資格証明の発行

このステップでは、ステップ2のレスポンスで受信したrequestStateのファクタ資格証明を発行します。authFactor属性はrequestStateに含まれるため、リクエスト・ペイロードには含まれないことに注意してください。クライアントには次の属性が含まれている必要があります:

  • op: クライアントが必要とする操作の種類をサーバーに指示します
  • requestState: ステップ2のレスポンスで受信

リクエストの例

次の例に、ファクタ資格証明を発行するためのJSON形式のPOSTリクエストのコンテンツを示します:

{  
   "op":"credSubmit",
   "credentials": {  
       "duoSecurityResponse": "AUTH
      |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjM5NjA=
      |f2d0df2a189219a8e85db190ac66fab33be996c3:APP
      |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1Njc0NTU=
      |a3b7c901e845ebd80451ab670473e983707a8459"
   },
   "requestState":"{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "authnToken": "{{authnToken}}",
    "status": "success",
    "ecId": "5MyZ41m0000000000"
}

Web SDK v4を使用したDuoセキュリティでのユーザー・アカウントの認証

このユースケースでは、アイデンティティ・ドメイン認証APIを使用して、Duo Web SDK v4でユーザー・アカウントを認証するステップ・バイ・ステップの例を示します。

ノート

Duo Web SDK v4を有効にする必要がある場合は、Duo Web SDKの有効化 v4を参照してください。
ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。
この使用例では、次のステップを使用します。各ステップには、リクエストおよびレスポンスの例が含まれます:
ノート

これらのステップでは、MFAが有効であり、MFAのサインオン・ポリシーが作成されていることを前提としています。「多要素認証設定の構成」を参照してください。

ステップ1: 認証フローの開始

最初のrequestStateを取得して、認証フローを開始します。

リクエストの例

cURL形式のリクエストの例を次に示します: 

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}
ノート

appNameはオプションです。appNameは、クライアントがアクセスするアプリケーションの名前です。appNameを指定すると、アプリケーションに固有のサインオン・ポリシーが処理され、クライアントは、そのポリシーに基づいて必要なファクタのチャレンジを受けます。

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ2: ユーザーの資格証明の発行

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "4uy3^1k0000000000",
    "nextAuthFactors": [
        "TOTP",
        "SECURITY_QUESTIONS",
        "DUO_SECURITY",
        "SMS",
        "EMAIL",
        "PUSH"
    ],
    "EnrolledAccountRecoveryFactorsDetails": {
        "EMAIL": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "displayName": "clarence.saladna@example.com"
                }
            ]
        },
        "enrolledAccRecFactorsList": [
            "EMAIL"
        ]
    },
    "TOTP": {
        "credentials": [
            "offlineTotp"
        ]
    },
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "scenario": "ENROLLMENT",
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitが送信されます。

ステップ3: Duoセキュリティ認証の開始

Duoセキュリティ認証中、ブラウザはDuoセキュリティ・サーバーにリダイレクトされ、Duoセキュリティ・サーバーは、ユーザーがセカンダリ認証を実行するセカンダリ認証ページをロードします。認証に成功すると、Duoセキュリティ・サーバーは状態(duoSecurityAuthzState)およびコード(duoSecurityAuthzCode)パラメータで応答します。認証を完了するには、これらのパラメータをアイデンティティ・ドメインに送信する必要があります。

次のステップを使用して、状態およびコード・パラメータを取得します。

  1. duoSecurityAuthzRequestからリダイレクト先のURLを取得します。

    例: 
    "duoSecurityAuthzRequest": "https://api-xxxxxxxx.duosecurity.com/oauth/v1/authorize?response_type=code&client_id=<client_id>&redirect_uri=duoSecurityAuthzRedirectURL&state=3047103d-d707-4b94-a960-203430071154&request=<request>"

    duoSecurityAuthzRedirectURLのリダイレクトURLです。

  2. Do 303「Duo Security Server」にリダイレクトします。

  3. Duoセキュリティの登録および認証プロセスを完了します。

    Duoセキュリティ・サーバーは、duoSecurityAuthzStateおよびduoSecurityAuthzCodeを使用してduoSecurityAuthzRedirectURLにリダイレクトします。

ステップ4: ファクタ資格証明の発行

認証を完了するには、レスポンスからアイデンティティ・ドメインにduoSecurityAuthzStateおよびduoSecurityAuthzCodeを渡します。

リクエストの例

JSON形式のリクエストのコンテンツの例を次に示します:

{
    "op": "credSubmit",
    "credentials":
   {
      "duoSecurityAuthzCode": "<duo-security-authz-code>",
      "duoSecurityAuthzState": "<duo-security-authz-state>"
   }
,
    "requestState": "requestState"}'

レスポンスの例 

{
    "authnToken": "{{authnToken}}",
    "status": "success",
    "ecId": "5MyZ41m0000000000"
}

バックアップ・ファクタとして使用する場合のDuoセキュリティによるユーザーの認証

このユースケースでは、アイデンティティ・ドメインREST APIを使用して、バックアップ・ファクタとして構成されている場合でもDuoセキュリティでユーザー・アカウントを認証するステップ・バイ・ステップの例を示します。

ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。
この使用例では、次のステップを使用します。各ステップには、リクエストおよびレスポンスの例が含まれます:

ステップ1: 認証フローの開始

最初のrequestStateを取得して、認証フローを開始します。

リクエストの例

cURL形式のリクエストの例を次に示します: 

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}
ノート

appNameはオプションです。appNameは、クライアントがアクセスするアプリケーションの名前です。appNameを指定すると、アプリケーションに固有のサインオン・ポリシーが処理され、クライアントは、そのポリシーに基づいて必要なファクタのチャレンジを受けます。

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ2: ユーザーの資格証明の発行

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "4uy3^1k0000000000",
    "nextAuthFactors": [
        "TOTP",
        "SECURITY_QUESTIONS",
        "DUO_SECURITY",
        "SMS",
        "EMAIL",
        "PUSH"
    ],
    "EnrolledAccountRecoveryFactorsDetails": {
        "EMAIL": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "displayName": "clarence.saladna@example.com"
                }
            ]
        },
        "enrolledAccRecFactorsList": [
            "EMAIL"
        ]
    },
    "TOTP": {
        "credentials": [
            "offlineTotp"
        ]
    },
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "scenario": "ENROLLMENT",
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。この例では、次のステップでgetBackupFactorsが送信されます。

ステップ3: バックアップ・ファクタのリストの取得

このステップでは、バックアップ・ファクタのリストを取得します。

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
    "op": "getBackupFactors",
    "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "5MyZ41p0000000000",
    "nextAuthFactors": [
        "EMAIL",
        "BYPASSCODE",
        "SECURITY_QUESTIONS",
        "DUO_SECURITY"
    ],
    "EMAIL": {
        "credentials": [
            "preferred",
            "deviceId"
        ],
        "enrolledDevices": [
            {
                "deviceId": "790ed820aee048a78de17ebe1ebddb19",
                "displayName": "ashXXXXX@oracle.com"
            }
        ]
    },
    "BYPASSCODE": {
        "credentials": [
            "bypassCode"
        ]
    },
    "SECURITY_QUESTIONS": {
        "credentials": [
            "questionId",
            "answer"
        ],
        "questions": [
            {
                "questionId": "FirstCar",
                "text": "What's the model of your first car?"
            }
        ],
        "preferred": true
    },
    "DUO_SECURITY": {
        "enrolledDevices": [
            {
                "deviceId": "3053eed6249a4dd4835c51bf873c5f85",
                "displayName": "jarvis's Duo Security Account"
            }
        ]
    },
    "nextOp": [
        "credSubmit",
        "getBackupFactors"
    ],
    "scenario": "AUTHENTICATION",
    "requestState": "{{requestState}}",
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    }
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ4: バックアップ・ファクタのリストからのDuoセキュリティの選択

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
    "op": "credSubmit",
    "authFactor": "DUO_SECURITY",
    "credentials": {
        "deviceId": "3053eed6249a4dd4835c51bf873c5f85"
    },
    "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
	"status": "success",
	"ecId": "5MyZ41q0000000000",
	"DUO_SECURITY": {
	"credentials": [
		 "duoSecurityResponse"
	],
	"authnDetails": {
		"duoSecurityChallenge": "TX
			 |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjQ1NDg=
			 |230d8328f53ec537ecd033fbb175fbce65930c3e:APP
			 |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1Njc4NDg=
			 |af94d927d3e027141177e8f88baa19f6427502ee",
		   "duoSecurityHost": "api-example.duosecurity.com"
		}
	},
	"nextOp": [
		"credSubmit",
	       "getBackupFactors"
	],
	"scenario": "AUTHENTICATION",
	"requestState": "{{requestState}}",
	"trustedDeviceSettings": {
		"trustDurationInDays": 15
	}
}

優先ファクタとしてのDuoセキュリティの設定

このユースケースでは、アイデンティティ・ドメインREST APIを使用して、Duoセキュリティを認証の優先ファクタとして設定するステップ・バイ・ステップの例を示します。

preferredフラグをtrueに設定すると、Duoセキュリティを優先ファクタとして設定できます(ユーザーがすでにDuoセキュリティ以外のファクタを持っている場合)。

ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。
この使用例では、次のステップを使用します。各ステップには、リクエストおよびレスポンスの例が含まれます:

ステップ1: 認証フローの開始

最初のrequestStateを取得して、認証フローを開始します。

リクエストの例

cURL形式のリクエストの例を次に示します: 

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}
ノート

appNameはオプションです。appNameは、クライアントがアクセスするアプリケーションの名前です。appNameを指定すると、アプリケーションに固有のサインオン・ポリシーが処理され、クライアントは、そのポリシーに基づいて必要なファクタのチャレンジを受けます。

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ2: ユーザーの資格証明の発行

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
   "status": "success",
   "ecId": "g5CAF1i1000000000",
   "nextAuthFactors": [
      "DUO_SECURITY"
    ],
    "DUO_SECURITY": {
      "credentials": [
         "duoSecurityResponse"
      ],
      "authnDetails": {
         "duoSecurityChallenge": "TX
            |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjM2Njc=
            |73894f83e7ee87c81388f84b4c0015cb86c6fd0b:APP
            |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjY5Njc=
            |11f57d2ad044abee78d3290fdff69af7c3d22d71",
         "duoSecurityHost": "api-example.duosecurity.com"
      }
    },
   "nextOp": [
      "credSubmit",
      "getBackupFactors"
    ],
    "scenario": "AUTHENTICATION",
    "requestState": "{{requestState}}",
    "trustedDeviceSettings": {
      "trustDurationInDays": 15
    }
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitが送信されます。

ステップ3: Duoセキュリティ認証の開始

DuoのWeb SDK v2を使用して、アイデンティティ・ドメインをDuoセキュリティと統合します。Duoは、セカンダリ認証に使用されるiFrameと対話するJavaScriptライブラリを提供します。

プライマリ認証の後、アイデンティティ・ドメインから受信したduoSecurityHostやduoSecurityChallengeなどの認証の詳細をiFrameに渡する必要があります。次の例を使用してDuoセキュリティ認証を開始し、iFrameをロードしてDuoセキュリティ・サーバーと接続できます。

function duo(msg, duoSecurityCallback) {
    Duo.init({iframe: "duo_iframe",
            host: msg.DUO_SECURITY.authnDetails.duoSecurityHost,
            sig_request: msg.DUO_SECURITY.authnDetails.duoSecurityChallenge,
            submit_callback: duoSecurityCallback,
            post_argument: "resp"
    });
}

Duo認証プロセスの完了後、DuoはduoSecurityCallbackメソッドをコールしてDuoレスポンスを取得します。

var duoSecurityCallback = function(details, credentials) {
       var credentials = {};
       credentials.duoSecurityResponse = details.firstElementChild.value;
       operation = "credSubmit";
       initiateAuth(credentials); 
}

Duoセキュリティのレスポンスを受信したら、レスポンスをアイデンティティ・ドメインに渡して認証を完了する必要があります。

ステップ4: 優先ファクタとしてのDuoセキュリティの有効化

このステップでは、優先ファクタとしてDuoセキュリティを有効にします。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
  "op": "credSubmit",
  "credentials": {
    "duoSecurityResponse": "AUTH
      |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjQzMzg=
      |4a40cc9c79d4a65b48d0f9b871d7a4e83481b3ca:APP
      |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1Njc4NDg=
      |af94d927d3e027141177e8f88baa19f6427502ee",
    "preferred": true
 },
 "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "authnToken": "{{authnToken}}",
    "status": "success",
    "ecId": "5MyZ41r0000000000"
}

Duoを認証ファクタとして使用する場合の信頼できるデバイスのサポート

このユースケースでは、Duoを認証ファクタとして使用する場合に、アイデンティティ・ドメインREST APIを使用して、信頼できるデバイスをサポートするステップ・バイ・ステップの例を示します。

ヒント

idm-samples GitHubリポジトリ内のidcs-authn-api-rest-clientsフォルダからアイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。
この使用例では、次のステップを使用します。各ステップには、リクエストおよびレスポンスの例が含まれます:

ステップ1: 認証フローの開始

最初のrequestStateを取得して、認証フローを開始します。

リクエストの例

cURL形式のリクエストの例を次に示します: 

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}
ノート

appNameはオプションです。appNameは、クライアントがアクセスするアプリケーションの名前です。appNameを指定すると、アプリケーションに固有のサインオン・ポリシーが処理され、クライアントは、そのポリシーに基づいて必要なファクタのチャレンジを受けます。

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitを送信する必要があります。requestStateには、リクエストの処理に必要なコンテキスト・データが含まれます。

ステップ2: ユーザーの資格証明の発行

最初のファクタ(ユーザー名とパスワード)としてユーザーの資格証明を発行します。このステップでは、クライアントに次の属性を含める必要があります:

  • credentials:のユーザー名とパスワード

  • requestState:ステップ1のレスポンスで受信した

  • op:クライアントが必要とする操作の種類をサーバーに指示します

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
   "status": "success",
   "ecId": "g5CAF1i1000000000",
   "nextAuthFactors": [
      "DUO_SECURITY"
    ],
    "DUO_SECURITY": {
      "credentials": [
         "duoSecurityResponse"
      ],
      "authnDetails": {
         "duoSecurityChallenge": "TX
            |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjM2Njc=
            |73894f83e7ee87c81388f84b4c0015cb86c6fd0b:APP
            |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjY5Njc=
            |11f57d2ad044abee78d3290fdff69af7c3d22d71",
         "duoSecurityHost": "api-example.duosecurity.com"
      }
    },
   "nextOp": [
      "credSubmit",
      "getBackupFactors"
    ],
    "scenario": "AUTHENTICATION",
    "requestState": "{{requestState}}",
    "trustedDeviceSettings": {
      "trustDurationInDays": 15
    }
}

レスポンスでは、nextOp値は、次のリクエストでop値として送信できる内容を示します。このユースケースの例では、次のステップでcredSubmitが送信されます。

ステップ3: Duoセキュリティ認証の開始

DuoのWeb SDK v2を使用して、アイデンティティ・ドメインをDuoセキュリティと統合します。Duoは、セカンダリ認証に使用されるiFrameと対話するJavaScriptライブラリを提供します。

プライマリ認証の後、アイデンティティ・ドメインから受信したduoSecurityHostやduoSecurityChallengeなどの認証の詳細をiFrameに渡する必要があります。次の例を使用してDuoセキュリティ認証を開始し、iFrameをロードしてDuoセキュリティ・サーバーと接続できます。

function duo(msg, duoSecurityCallback) {
    Duo.init({iframe: "duo_iframe",
            host: msg.DUO_SECURITY.authnDetails.duoSecurityHost,
            sig_request: msg.DUO_SECURITY.authnDetails.duoSecurityChallenge,
            submit_callback: duoSecurityCallback,
            post_argument: "resp"
    });
}

Duo認証プロセスの完了後、DuoはduoSecurityCallbackメソッドをコールしてDuoレスポンスを取得します。

var duoSecurityCallback = function(details, credentials) {
       var credentials = {};
       credentials.duoSecurityResponse = details.firstElementChild.value;
       operation = "credSubmit";
       initiateAuth(credentials); 
}

Duoセキュリティのレスポンスを受信したら、レスポンスをアイデンティティ・ドメインに渡して認証を完了する必要があります。

ステップ4: 信頼できるデバイスとしてのデバイスの有効化

このステップでは、デバイスを信頼できるデバイスとして有効にします。デバイスが信頼されると、Duoセキュリティが登録されている場合もMFAはチャレンジを受けません。

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します:

{
   "op": "credSubmit",
   "credentials": {
       "duoSecurityResponse": "AUTH
         |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjQ2MDY=
         |ba16e2eb734e00d9ebe6f8129ce32669437052e9:APP
         |amFydmlzfERJNThZNFhVMlFXWEVSUDQzVTRKfDE1NjE1NjgwNjc=
         |ba4f415559ff2c30b23a912a18ee5f717a398563"
   },
   "trustedDevice": true,
   "trustedDeviceDisplayName": "Postman on Windows",
   "requestState": "{{requestState}}"
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "authnToken": "{{authnToken}}",
    "trustToken": "{{trustToken}}",
    "status": "success",
    "ecId": "5MyZ41u0000000000"
}

セルフサービスを使用したDuoセキュリティによるMFAの登録

このユースケースでは、Duoセキュリティを使用したマルチファクタ認証(MFA)でのセルフサービス登録に、アイデンティティ・ドメインREST APIを使用するステップ・バイ・ステップの例を示します。

idm-samples GitHubリポジトリ内のidcs-rest-clientsフォルダから、アイデンティティ・ドメイン認証ユースケース・サンプル・コレクションおよびグローバル変数ファイルをダウンロードし、Postmanにインポートします。

前提条件のステップとして、これらのステップを実行する前にMEトークンを取得する必要があります。MEトークンの取得の詳細は、「認証APIを使用したアクセス・トークンの生成」を参照してください。

このユース・ケースでは、次のステップを実行します。
ノート

これらのステップでは、「多要素認証設定の構成」を使用して、MFAの関連ファクタを有効にすることを前提としています。

Step1: Duoファクタへのユーザーの登録

このステップでは、/admin/v1/MyAuthenticationFactorEnrollerエンドポイントに対するPOSTリクエストでDuoセキュリティ登録を開始します。クライアントには次の属性が含まれている必要があります:
  • value: ユーザーIDを定義します。{{HOST}}/admin/v1/MeにGETコールを実行して、"id"値を取得できます。

リクエストの例

JSON形式のPOSTリクエスト本文のコンテンツの例を次に示します: 

{
   "authnFactors":["THIRDPARTY"],
   "thirdPartyFactor": {
       "thirdPartyVendorName" : "DUO_SECURITY",
       "thirdPartyFactorType" : "None"
   },
   "user": {
      "value" : "012832e2e63d4bfda5bc512f2b52ccbe"
    },
   "schemas": [
       "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
   ]
}

レスポンスの例

次の例に、レスポンスボディーの内容を JSON形式で示します。 

{
    "authnFactors": [
        "THIRDPARTY"
    ],
    "thirdPartyFactor": {
        "thirdPartyFactorId": "1c3a069c240b4a9d9e6e90b9a2be8bed",
        "thirdPartyFactorType": "None",
        "thirdPartyVendorName": "DUO_SECURITY"
    },
    "user": {
        "value": "6852e4e2bc864b3b912d7bd48f9f4879",
        "$ref": "https://<domainURL>admin/v1/Users/6852e4e2bc864b3b912d7bd48f9f4879"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
    ],
    "meta": {
        "resourceType": "MyAuthenticationFactorEnroller",
        "location": "https://<domainURL>admin/v1/MyAuthenticationFactorEnroller"
    },
    "displayName": "test's Phone",
    "requestId": "fe520538-0da6-45a3-b23f-1256091e3f0c",
    "deviceId": "ca0ba497327c45d2a4a408301c78682b"
}

レスポンスでは、次のステップでdeviceIdおよびrequestIdを渡す必要があります。

ステップ2: ユーザーのDuo認証の開始

このステップでは、/admin/v1/MyAuthenticationFactorInitiatorエンドポイントに対するPOSTリクエストを発行することによって、サードパーティ側で認証を開始します。クライアントには次の属性が含まれている必要があります:

  • requestId:ステップ1のレスポンスで受信
  • deviceId:ステップ1のレスポンスで受信
  • userName:ユーザーのユーザー名

リクエストの例

JSON形式のPOSTリクエスト本文のコンテンツの例を次に示します:

{
    "requestId": "1e513691-9a41-4418-a0f0-f96e6f4c5735",
    "deviceId": "14a2a6f2f41b4c10acc9a6d4b54ffe4a",
    "authFactor": "THIRDPARTY",
    "thirdPartyFactor": {
        "thirdPartyFactorId": "7ed55e203ac7435eb6b4847dcfca28e0",
        "thirdPartyFactorType": "None",
        "thirdPartyVendorName": "DUO_SECURITY"
    },
    "userName": "testuser1",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ]
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します:

{
    "requestId": "fe520538-0da6-45a3-b23f-1256091e3f0c",
    "deviceId": "ca0ba497327c45d2a4a408301c78682b",
    "authFactor": "THIRDPARTY",
    "thirdPartyFactor": {
        "thirdPartyFactorId": "1c3a069c240b4a9d9e6e90b9a2be8bed",
        "thirdPartyFactorType": "None",
        "thirdPartyVendorName": "DUO_SECURITY"
    },
    "userName": "testuser1",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ],
    "meta": {
        "resourceType": "MyAuthenticationFactorInitiator",
        "location": "https://<domainURL>admin/v1/MyAuthenticationFactorInitiator"
    },
    "additionalAttributes": [
        {
            "name": "duoHost",
            "value": "api-0095dc4a.duosecurity.com"
        },
        {
            "name": "duoChallenge",
            "value": "TX
               |Njg1MmU0ZTJiYzg2NGIzYjkxMmQ3YmQ0OGY5ZjQ4Nzl8RElFWldUV0VMVUJYSEQ2RExKM1V8MTU0MDMyMDkz==
               |8a0b6f0472b1c03357e9d6b3348d0a341c96e6a0:APP
               |Njg1MmU0ZTJiYzg2NGIzYjkxMmQ3YmQ0OGY5ZjQ 4Nzl8RElFWldUV0VMVUJYSEQ2RExKM1V8MTU0MDMyNDIzNA==
               |5d45c215e6e5af7d866df480087d825aa1cf4279"
        }
    ]
}

レスポンスでは、次のステップでdeviceIdおよびrequestIdを渡す必要があります。

ステップ3: 登録シナリオのDuoファクタの検証

このステップでは、収集された資格証明を使用してサードパーティのファクタAPIをコールし、/admin/v1/MyAuthenticationFactorValidatorエンドポイントに対するPOSTリクエストでユーザーの登録を検証します。

クライアントには次の属性が含まれている必要があります:

  • requestId:ステップ2のレスポンスで受信
  • deviceId:ステップ2のレスポンスで受信

リクエストの例

次の例に、JSON形式のPOSTリクエストのコンテンツを示します: 

{
    "requestId": "1e513691-9a41-4418-a0f0-f96e6f4c5735",
    "deviceId": "14a2a6f2f41b4c10acc9a6d4b54ffe4a",
    "authFactor": "THIRDPARTY",
    "thirdPartyFactor": {
        "thirdPartyFactorId": "7ed55e203ac7435eb6b4847dcfca28e0",
        "thirdPartyFactorType": "None",
        "thirdPartyVendorName": "DUO_SECURITY"
    },
    "scenario": "ENROLLMENT",
    "username": "testuser1",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
    ],
    "additionalAttributes": [
        {
            "name": "duoResponse",
            "value": "AUTH|YWJoaXNoZWsuanVsa2FAb3JhY2xlLmNvbXxESUVaV1RXRUxVQlhIRDZETEozVXwxNTM5ODMwNDc2|9439adbea1b90a90c9169f366cc028aabde8ac51:APP|YWJoaXNoZWsuanVsa2FAb3JhY2xlLmNvbXxESUVaV1RXRUxVQlhIRDZETEozVXwxNTM5ODMzODYx|94bcc9a0c4ab6da617827432d021171d3b393fd3"
        }
    ]
}

レスポンスの例

JSON形式のレスポンスのコンテンツの例を次に示します: 

{
    "requestId": "fe520538-0da6-45a3-b23f-1256091e3f0c",
    "deviceId": "ca0ba497327c45d2a4a408301c78682b",
    "authFactor": "THIRDPARTY",
    "thirdPartyFactor": {
        "thirdPartyFactorId": "1c3a069c240b4a9d9e6e90b9a2be8bed",
        "thirdPartyFactorType": "None",
        "thirdPartyVendorName": "DUO_SECURITY"
    },
    "scenario": "ENROLLMENT",
    "userName": "testuser1",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
    ],
    "meta": {
        "resourceType": "MyAuthenticationFactorValidator",
        "location": "https://<domainURL>admin/v1/MyAuthenticationFactorValidator"
    },
    "status": "SUCCESS",
    "displayName": "test's Phone",
    "mfaStatus": "ENROLLED",
    "mfaPreferredDevice": "0d37a1334bdf4c9ca80474dcadba8d10",
    "mfaPreferredAuthenticationFactor": "THIRDPARTY",
    "mfaPreferredThirdPartyFactorType": "None",
    "securityQuestionsPresent": false,
    "devicesCount": 1,
    "emailFactorEnrolled": false
}

レスポンスで、属性mfaStatus:"ENROLLED"は、ユーザーがMFAに登録したことを示します。mfaPreferredAuthenticationFactor属性は、優先メソッドとして設定されたファクタを示します。この例ではTHIRDPARTYです。