search
how tos

Configure a Second Factor

If you set up Second-Factor Authentication(2FA), you can configure a verification code as the second factor. This page demonstrates the process over REST.

This procedure uses REST calls available from the Express Postman collection. For more information, see how you can Get Started With Postman:

  1. Get an access token for your tenant. Substitute your tenant name, username, and password in the following REST call:

    content_copy COPY

    curl -X POST \
    https://openam-{tenantName}.forgeblocks.com/am/json/realms/root/authenticate \
    -H 'Content-Type: application/json' \
    -d '{
       "userName":"<Username>",
       "password":"<Password>"
    }'
    


  2. For this procedure, create a new web app. Substitute your tenant name, along with the access token from the previous step:

    content_copy COPY

    curl -X POST \
      https://api-{tenantName}.forgeblocks.com/v1/apps \
      -H 'Authorization: Bearer {accessToken}' \
      -H 'Content-Type: application/json' \
      -d '{
      "accessTokenLifetime": 3600,
      "advancedOAuth" : {
     	"tokenEndpointAuthMethod": "client_secret_basic"
      },
      "apiScopes": [
        "me.read",
        "me.update",
        "me.update-password",
        "password-policy.read",
        "password-policy.update",
        "user.reset-password",
        "user.recover-username",
        "user.create",
        "user.read",
        "openid",
        "profile",
        "email",
        "address",
        "phone"
      ],
      "authorizationCodeLifetime": 120,
      "customClaims": {},
      "description": "My great sample web app",
      "enabled": true,
      "grantTypes": {
        "authorizationCode": true,
        "refreshToken": true,
        "clientCredentials": true,
        "password": true
      },
      "jwtSigningAlgorithm": "RS256",
      "jwtTokenLifetime": 3600,
      "loginRedirectUris": ["https://example.com/homeLogin/"],
      "logoutRedirectUris": ["https://example.com/homeLogout/"],
      "name": "Sample Web App",
      "refreshTokenLifetime": 604800,
      "type": "web"
    }'
    


  3. For password policies, disable email verification of password changes. In the following REST call, the relevant entry is "requireEmailVerification": false.

    curl -X PUT \
      https://api-{tenantName}.forgeblocks.com/v1/password-policy \
      -H 'Authorization: Bearer {accessToken}' \
      -H 'Content-Type: application/json' \
      -d '{
        "disallowFirstNamePart": true,
        "disallowLastNamePart": true,
        "lockoutPasswordAttempts": 0,
        "maxPasswordAge": 0,
        "minPasswordLength": 8,
        "requireEmailVerification": false,
        "requireLowerCaseLetter": true,
        "requireNumber": true,
        "requireSymbol": true,
        "requireUpperCaseLetter": true,
        "selfServeUnlockDuration": 1
    }'
    
  4. (Optional) You can configure a separate outgoing email server. For more information, see Configure SMTP Email.

  5. Create a new user. For this procedure, include your email address. One way to do so is with the following REST call. If successful, the output will include an id, which you’ll need to save for the next step:

    content_copy COPY

    curl -X POST \
    'https://api-{tenantName}.forgeblocks.com/v1/users' \
    -H 'Authorization: Bearer {accessToken}' \
    -H 'Content-Type: application/json' \
    -d '{
      "password":"<Password>",
      "userName":"<Username>",
      "emails":[
        {
          "value":"<yourEmailAddress>"
        }
      ],
      "name":{
        "familyName":"<lastName>",
        "givenName":"<firstName>"
      }
    }'
    
  6. Now get an access token for that user. You’ll see that access token in the output as authId.

    content_copy COPY

    curl -X POST \
    'https://openam-{tenantName}.forgeblocks.com/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=SecondFactor' \
    -H 'Accept-API-Version: resource=2.0,protocol=1.0' \
    -H 'Cookie: amlbcookie=01' 
    
  7. With that access token (shown in the output as authId), take a target username and password. The call specifies that this is the UsernamePassword stage of 2FA:

    content_copy COPY

    curl -X POST \
      'https://openam-{tenantName}.forgeblocks.com/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=SecondFactor' \
      -H 'Accept-API-Version: resource=2.0,protocol=1.0' \
      -H 'Content-Type: application/json' \
      -H 'Cookie: amlbcookie=01' \
      -d '{
      "authId": "{accessToken}"
      "callbacks": [
        {
          "type": "NameCallback",
          "output": [
            {
              "name": "prompt",
              "value": "User Name"
            }
          ],
          "input": [
            {
              "name": "IDToken1",
              "value": "{userName}"
            }
          ],
          "_id": 0
        },
        {
          "type": "PasswordCallback",
          "output": [
            {
              "name": "prompt",
              "value": "Password"
            }
          ],
          "input": [
            {
              "name": "IDToken2",
              "value": "{userPassword}"
            }
          ],
          "_id": 1
        }
      ],
      "stage": "UsernamePassword"
    }'
    


  8. Express offers two options for second-factor authentication: email or SMS. For more information, see Second-Factor Authentication. The following REST call defaults to email:

    content_copy COPY

    curl -X POST \
      'https://openam-{tenantName}.forgeblocks.com/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=SecondFactor' \
      -H 'Accept-API-Version: resource=2.0,protocol=1.0' \
      -H 'Content-Type: application/json' \
      -H 'Cookie: amlbcookie=01' \
      -d '{
      "authId": "{accessToken}",
      "callbacks": [
        {
          "type": "ChoiceCallback",
          "output": [
            {
              "name": "prompt",
              "value": "SecondFactorChoice"
            },
            {
              "name": "choices",
              "value": [
                "Email",
                "SMS"
              ]
            },
            {
              "name": "defaultChoice",
              "value": 0
            }
          ],
          "input": [
            {
              "name": "IDToken1",
              "value": 0
            }
          ],
          "_id": 2
        }
      ],
      "stage": "SecondFactorChoice"
    }'
    


  9. The final REST call sends an email with a verification code, using the Verification Code template. For more information, see Customize Email Templates:

    content_copy COPY

    curl -X POST \
    'https://openam-{tenantName}.forgeblocks.com/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=SecondFactor' \
    -H 'Accept-API-Version: resource=2.0,protocol=1.0' \
    -H 'Cookie: amlbcookie=01' 
    

When you’ve run these REST calls, the user specified in the UsernamePassword REST calls should receive an email in the following format:

Email template for a verification code


For questions or feedback, contact us.