Sample IdP Workflows

The following are samples of the authentication workflows incorporating the supported authentication methods, actions and customization.

Each sample can be called with the POST https://[base-server-url]/configuration/<tenant>/v2/Custo/IDPWorkflows

One-Time Temporary Password or Static Password plus Push Authentication

This sample contains the following authentication flows based on the user's existing authenticators:

  • If the user does NOT have a push-based authenticator - one-step authentication using a one-time temporary password

  • If the user has a push-based authenticator - two-step authentication using static password then push-based authentication

Copy

Temporary/static password plus push authentication

{
  "schemas": [
    "urn:hid:scim:api:idp:2.0:Customization"
  ],
  "id": "ID_TEMP_OR_UP_PUSH",
  "payload": {
    "theme_id": "ID_THEME1",
    "accessCriteria": [
      {
        "accessCriteriaId": "access_criteria.common_to_all",
        "authenticators": {
          "firstFactorsFiltering": true,
          "secondFactorsFiltering": true,
          "acrFiltering": false,
        }
	  }
    ],
    "actions": [
      {
        "actionId": "action.change_password",
        "accessCriteriaId": "access_criteria.common_to_all",
        "class": "CHANGE_PWD",
        "retry": 3
      },
      {
        "actionId": "action.reset_password",
        "accessCriteriaId": "access_criteria.common_to_all",
        "class": "SET_PWD",
        "retry": 3
      },
      {
        "actionId": "action.request_reset_password",
        "accessCriteriaId": "access_criteria.common_to_all",
        "class": "RESET_PWD",
        "retry": 3,
        "resetPasswordMethods": {
          "email": {
            "template": "<myemailtemplatevalue>",
            "templateHtml": false
          },
          "sms": {
            "template": "<mysmstemplatevalue>"
          }
        },
        "next_action": "action.reset_password"
      }
    ],
    "firstFactors": [
      {
        "factorId": "factor.user_pasword_temporary",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_TEMPPWD",
        "class": "LOGIN",
        "acr": "acr_up_temp",
        "step_up": "notRequired",
        "retry": 3,
      },
      {
        "factorId": "factor.user_pasword",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_CUSTPWD",
        "class": "LOGIN",
        "acr": "acr_up",
        "step_up": "required",
        "retry": 3,
        "actions": [
          "action.change_password",
          "action.request_reset_password"
        ]
      }
    ],
    "secondFactors": [
      {
        "factorId": "factor.push_authentication",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_PASA-2FA",
        "class": "PUSH",
        "acr": "acr_push",
        "retry": 3,
        "okStatus": "approved",
        "upon": "factor.user_pasword",
        "allowUserDeviceSelection": true
      }
    ]
  }
}

Where:

  • "acrFiltering" is set to false so any acr_values in the authorization request will be ignored.

  • "step_up" is set to "notRequired" for the temporary password authentication so secondary authentication/step up is not required.

  • "step_up" is set to "required" for static password authentication so secondary authentication/step up is required.

  • "upon" is set to "factor.user_pasword" so push is only required as the secondary authentication when static password is the first factor.

Static Password or Static Password plus Automatic Step-up if Push Available

This sample contains the following authentication flows based on the user's existing authenticators:

  • If the user does NOT have a push-based authenticator - one-step authentication using static password

  • If the user has a push-based authenticator - two-step authentication using static password then push-based authentication

Copy

Static password plus step-up if push authentication available

{
  "schemas": [
    "urn:hid:scim:api:idp:2.0:Customization"
  ],
 
  "id": "ID_UP_PUSH_AUTOMATIC",
  "payload": {
    "theme_id": "ID_THEME1",
    "accessCriteria": [
      {
        "accessCriteriaId": "access_criteria.common_to_all",
        "authenticators": {
          "firstFactorsFiltering": true,
          "secondFactorsFiltering": true,
          "acrFiltering": false
        }
      }
    ],
    "actions": [
      {
        "actionId": "action.reset_password",
        "accessCriteriaId": "access_criteria.common_to_all",
        "class": "SET_PWD",
        "retry": 3
      },
      {
        "actionId": "action.request_reset_password",
        "accessCriteriaId": "access_criteria.common_to_all",
        "class": "RESET_PWD",
        "retry": 3,
        "resetPasswordMethods": {
          "email": {
            "template": "<myemailtemplatevalue>",
            "templateHtml": false
          }
        },
        "next_action": "action.reset_password"
      }
    ],
    "firstFactors": [
      {
        "factorId": "factor.user_pasword",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_CUSTPWD",
        "class": "LOGIN",
        "acr": "acr_up",
        "step_up": "automatic",
        "retry": 3,
        "actions": [
          "action.request_reset_password"
        ]
      }
    ],
    "secondFactors": [
      {
        "factorId": "factor.push_authentication",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_PASA-2FA",
        "class": "PUSH",
        "acr": "acr_push",
        "retry": 3,
        "okStatus": "approved",
        "upon": "factor.user_pasword",
        "allowUserDeviceSelection": true
      }
    ]
  }
}

Where:

  • "acrFiltering" is set to false so any acr_values in the authorization request will be ignored.

  • "step_up" is set to "automatic" so if the user has a push-based authenticator available, then step-up authentication is automatically requested. If not, the static password is sufficient for authentication.

Static Password or One-Time Password with Customized Messages/Labels

This sample contains the following authentication flows based on the user's existing authenticators:

  • If the user does NOT have an OTP authenticator - one-step authentication using static password with customized messages/labels and available actions to change the password or reset a forgotten password via SMS

  • If the user has an OTP authenticator - one-step authentication using a one-time password with customized messages/labels

Copy

Static password or OTP with customized interface content

{
  "schemas": [
    "urn:hid:scim:api:idp:2.0:Customization"
  ],
  "id": "ID_UP_OR_OTP",
  "payload": {
    "theme_id": "ID_THEME1",
    "accessCriteria": [
      {
        "accessCriteriaId": "access_criteria.common_to_all",
        "authenticators": {
          "firstFactorsFiltering": true,
          "secondFactorsFiltering": true,
          "acrFiltering": true
        },
        }
    ],
    "actions": [
      {
        "actionId": "action.reset_password",
        "accessCriteriaId": "access_criteria.common_to_all",
        "class": "SET_PWD",
        "retry": 3
      },
      {
        "actionId": "action.request_reset_password",
        "accessCriteriaId": "access_criteria.common_to_all",
        "class": "RESET_PWD",
        "retry": 3,
        "resetPasswordMethods": {
          "sms": {
            "template": "<mysmstemplatevalue>"
          }
        },
        "next_action": "action.reset_password"
      }
    ],
    "firstFactors": [
      {
        "factorId": "factor.user_static_pasword",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_CUSTPWD",
        "class": "LOGIN",
        "acr": "acr_up",
        "retry": 3,
        "actions": [
          "action.change_password",
          "action.request_reset_password"
        ],
        "localizationKeyRedefinition": {
          "LOGIN.name": "LOGIN.name.user_static_pasword",
          "LOGIN.tooltip": "LOGIN.tooltip.user_static_pasword",
          "LOGIN.input.password.label": "LOGIN.input.password.label.user_static_pasword"
        }
      },
      {
        "factorId": "factor.otp_token",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_CUSTOTP",
        "class": "OTP",
        "acr": "acr_otp",
        "upon": "factor.user_pasword",
        "localizationKeyRedefinition": {
          "OTP.name": "OTP.name.otp_token",
          "OTP.tooltip": "OTP.tooltip.otp_token",
          "OTP.input.otp.label": "OTP.input.otp.label.otp_token"
        }
      }
    ]
  }
}

Where:

  • The corresponding theme configuration contains the following message/label customization:

    Copy

    Theme fragment (POST https://[base-server-url]/configuration/<tenant>/v2/Custo/IDPThemes)

    "localization": {
    "extensions": {},
      "hid_portal": {
        "en": {
         
          "LOGIN.name": "Static Password",
          "LOGIN.tooltip": "Authenticate using your password",
          "LOGIN.input.password.label": "Password",
 
           #localizationKeyRedefinition for my specific factor
          "LOGIN.name.user_static_pasword": "my custom Static Password",
          "LOGIN.tooltip.user_static_pasword": "Authenticate using Static password",
          "LOGIN.input.password.label.user_static_pasword": "Static Password",
  
          "OTP.name": "One-Time Password",
          "OTP.tooltip": "Authenticate using an OTP generated on your token device",
          "OTP.input.otp.label": "One-Time Password",
           
           #localizationKeyRedefinition  for my specific factor
          "OTP.name.otp_token": "HID Approve One-Time Password ",
          "OTP.tooltip.otp_token": "Authenticate using an OTP generated on your HID Approve device",
          "OTP.input.otp.label.otp_token": "One-Time Password",

Standard OTP via OOB Triggered by Activation Code

This sample contains a two-step authentication flow where the user first validates an activation code which triggers the delivery of an OTP via email or SMS (OOB) based on the user's selection. The user then authenticates with the OTP.

Copy

OTP via OOB

{
  "schemas": [
    "urn:hid:scim:api:idp:2.0:Customization"
  ],
  "id": "ID_ACCODE_OTP_OOB",
  "payload": {
    "theme_id": "ID_THEME1",
    "accessCriteria": [
      {
        "accessCriteriaId": "access_criteria.common_to_all",
        "authenticators": {
          "firstFactorsFiltering": true,
          "secondFactorsFiltering": true,
          "acrFiltering": false
        }
      }
    ],
    "firstFactors": [
      {
        "factorId": "factor.oob_user_accode",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_OOB",
        "class": "CODE",
        "retry": 3,
        "step_up": "required",
        "oobMethods": {
          "email": {
            "template": "<myemailtemplatevalue>",
            "templateHtml": false
          },
          "sms": {
            "template": "<mysmstemplatevalue>"
          }
        }
      }
    ],
    "secondFactors": [
      {
        "factorId": "factor.otp_user_accode",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_OOB",
        "class": "OTP",
        "retry": 3,
        "upon": "factor.oob_user_accode"
      }
    ]
  }
}

Where:

  • "class" is set to "CODE" so the user validates the activation code as input and triggers the OTP delivery via the OOB method.

  • "oobMethods" is set to either email or SMS so the user is prompted to select the preferred OOB channel for OTP delivery.

    If not defined, the server will select the delivery adapter based on user information and authentication policy.

  • "code" is set to "AT_OOB" for the Activation code credential and the OTP credential as both factors must use the same policy.

Static Password then OTP via OOB

This sample contains a two-step authentication flow where the user first enters their static password. The user is then prompted to select the preferred OOB channel (email or SMS) for the delivery of an OTP. The validated selection triggers the delivery of an OTP. The user then authenticates with the OTP.

Copy

Static password then OTP via OOB

{
  "schemas": [
    "urn:hid:scim:api:idp:2.0:Customization"
  ],
  "id": "ID_UP_OTP_OOB",
  "payload": {
    "theme_id": "ID_THEME1",
    "accessCriteria": [
      {
        "accessCriteriaId": "access_criteria.common_to_all",
        "authenticators": {
          "firstFactorsFiltering": true,
          "secondFactorsFiltering": true,
          "acrFiltering": false
        }
      }
    ],
    "firstFactors": [
      {
        "factorId": "factor.user_pasword",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_CUSTPWD",
        "class": "LOGIN",
        "acr": "acr_up",
        "step_up": "required",
        "retry": 3,
        "actions": [
          "action.request_reset_password"
        ]
      }
    ],
    "secondFactors": [
      {
        "factorId": "factor.otp_oob_server2",
        "accessCriteriaId": "access_criteria.common_to_all",
        "code": "AT_OOB",
        "class": "OOB", 
        "retry": 3,
        "upon": "factor.user_pasword",
        "oobMethods": {
          "email": {
            "template": "<myemailtemplatevalue>",
            "templateHtml": false
          },
          "sms": {
            "template": "<mysmstemplatevalue>"
          }
        }
      }
    ]
  }
}

Where:

  • "class" is set to "OOB" so the server triggers the delivery of the OTP based on user information (email, phone number) and delivery method selected by user from the listed "oobMethods".

FIDO Enrollment and Authentication

This sample contains the workflow for FIDO enrollment (if required) and authentication, both protected by static password authentication.

Secondary authentication/step up is not required.

Copy

FIDO enrollment protected by static password and authentication as a first factor that does not require secondary/step-up authentication

{
	"schemas": [
		"urn:hid:scim:api:idp:2.0:Customization"
	],
	"id": "ID_FLOWFIDO",
	"payload": {
		"accessCriteria": [
			{
				"accessCriteriaId": "access_criteria.common_to_all",
				"authenticators": {
					"firstFactorsFiltering": false,
					"secondFactorsFiltering": false
				}
			}
		],
		"enrollProtectionFactors": [
			{
				"protectionFactorId": "enroll_protection.user_password",
				"code": "AT_EMPPWD",
				"type": "LOGIN",
				"retry": 3
			}
		],
		"enrollActions": [
			{
				"enrollId": "enroll_action.fido",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "FIDO",
				"code": "AT_FIDO",
				"rpId": "hostname"
				"userVerification": "required",
				"residentKey": "required",
				"authenticatorAttachment": "cross-platform",
				"allowedAAGUIDs": ["b93fd961-f2e6-462f-b122-82002247de78","ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4"],
				"retry": 1,
				"deviceType": "DT_FIDO",
				"credentialType": "CT_FIDOU2F",
				"deviceBinding": "required",
				"attestationVerification": "direct",
				"enrollValidation": true,
				"protectionFactor": "enroll_protection.user_password"
			}
		],
		"firstFactors": [
			{
				"factorId": "factor.user_password",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "LOGIN",
				"code": "AT_EMPPWD",
				"acr": "1",
				"stepUp": "required",
				"retry": 3,
				"actions": [
					"action.change_password",
					"action.forgot_password"
				]
			},
			{
				"factorId": "factor.fido",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "FIDO",
				"code": "AT_FIDO",
				"rpId": "hostname"
				"acr": "acr_fido",
				"stepUp": "notRequired",
				"retry": 3,
				"userVerification": "required",
				"discoverCredentialsInDevice": "true",
				"enrollActions": [
					"enroll_action.fido"
				]
			}
		],
		"secondFactors": [
			{
				"factorId": "factor.fido.2fa",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "FIDO",
				"code": "AT_FIDO",
				"acr": "acr_fido",
				"retry": 3,
				"upon": [
					"factor.user_password"
				],
				"userVerification": "discouraged",
				"enrollActions": [
					"enroll_action.fido"
				]
			}
		]
	}
}

Where the enrollment action (enroll.action.fido) will be available to the user in the logon interface with the following configuration:

  • The user is required to prove their physical presence (such as tapping the FIDO passkey or pressing the button):

    "userVerification": "required"

  • The device must allow the creation of a resident key for the HID Authentication Service credential:

    "residentKey": "required"

  • The user will be able to select the platform experience according to the type of their FIDO passkey (device-bound or synced):

    "authenticatorAttachment": "cross-platform"

  • The user can only enroll FIDO passkeys that correspond to a defined list of AAGUIDs:

    "allowedAAGUIDs": ["b93fd961-f2e6-462f-b122-82002247de78","ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4"]

  • The user must have a have a "pending" device of the specified device type:

    "deviceBinding": "required"

    You must create and assign a FIDO device authenticator for the user before they can enroll their passkey.

  • The user can only enroll a FIDO passkey verified for use by your organization:

    "attestationVerification": "direct"

  • The user must validate their enrollment by successfully authenticating with their FIDO passkey:

    "enrollValidation": true

  • The user must successfully authenticate with their static password to access the protected enrollment process:

    "protectionFactor": "enroll_protection.user_password"

After successful enrollment, FIDO authentication is then available for the user as a:

  • First authentication factor (factor.fido) where secondary/step-up authentication is not required:

    "stepUp": "notRequired"

  • Second authentication factor if the user authenticates with the static password as their first factor:

    "upon": ["factor.user_password"]

  • The user can only authenticate with a credential from a list of discoverable keys proposed by the workflow:

    "discoverCredentialsInDevice": "true",