As discussed in authentication and authorization, interactive authentication of a user is handled by the Data Governance Broker’s authorization endpoint. This endpoint presents the user with a chain of authentication steps, each of which is handled by a server-side component called an identity authenticator. The stock identity authenticators include:
- Username/password login
- External identity provider login (Google, Facebook, OpenID Connect, or SAML)
- One-time password sent to an email address
- One-time password sent to a telephone number using SMS or voice
- Time-based one-time password (TOTP) verification using an authenticator app, such as Google Authenticator or Authy
A user may be prompted to satisfy any number of identity authenticators and in any order, but typically, the user is prompted for a username and password to establish a login, and might then be prompted to provide a one-time password as a second authentication factor. For that reason, we’ll refer to the one-time password authenticators as second factors.
Enabling a second authentication factor
The sample configuration provided with the starter schema includes a boolean user attribute called
secondFactorEnabled. The Data Governance Broker’s default authentication policies will look for a value of
true to determine whether a user may be prompted to authenticate with a second factor.
In addition, the default second factor authenticators require setup of their own using special SCIM sub-resources:
- To deliver a one-time password to an email address, the user’s ownership of that email address must be confirmed using the validated email addresses sub-resource.
- To deliver a one-time password to a phone number, the user’s ownership of that phone number must be validated using the validated phone numbers sub-resource.
- To set up time-based one-time password authentication, the user’s authenticator app must be provisioned with a secret key value using the TOTP shared secret sub-resource.
The setup processes for these SCIM sub-resources all follow a similar pattern:
- Send a POST request to the sub-resource to initiate the process. Depending on the sub-resource, this might cause the Data Governance Broker to deliver a one-time password to the user. The response will include a field or ID with encrypted state information that the client will use in a subsequent step. The response might also include information that the client will need to use to build a prompt for the user.
- The client prompts the user to enter a one-time password.
- The client submits the encrypted state information and the one-time password to the Data Governance Broker using a PUT request.
Example: Validating ownership of an email address
To make this more tangible, we’ll show an example of how to validate that a user is in possession of a particular email address.
The first step is to send a POST request to the user’s
validatedEmailAddresses sub-resource. This request contains:
- The path to the attribute representing the email address to confirm — in this case,
- The user’s email address value.
- The subject of the message to send to the user.
- The message text. The text must include the placeholder value
%code%, into which the Data Governance Broker will insert a random one-time code.
final String id = "a13523d8-b6fd-35e0-adca-bdbe434645a5"; EmailValidationRequest emailValidation = new EmailValidationRequest("secondFactorEmail"); emailValidation.setAttributeValue("firstname.lastname@example.org"); emailValidation.setMessageSubject("Please confirm your email address"); emailValidation.setMessageText("Your verification code: %code%"); String emailValidationEndpoint = "Users/" + id + "/validatedEmailAddresses"; emailValidation = scimService.create(emailValidationEndpoint, emailValidation);
When the Data Governance Broker receives this request, it will send a random one-time code to the user’s email address. The client then prompts the user to enter this code.
Once the user provides the one-time code, the client adds it to the response that it previously received and performs a PUT.
If the Data Governance Broker accepts the code, then the request will succeed, and the email address is now validated.
Finally, the client must mark the user as enabled for second factor authentication, so it then sets the user’s
secondFactorEnabled flag to
scimService.modifyRequest("Users", id) .replaceValue("secondFactorEnabled", true) .invoke(GenericScimResource.class);
The user will now be ready to authenticate using a second factor.