User

The User object is used to get information (mostly from the "Auth" integration) about the users in your account.

Creating a new User

A new User can be be made as an instance of the main User class:

<?php
$user = new \DuoAuth\User();
$user->username = 'test1';
$user->realname = 'My User'
$user->save();
?>

Fetching data about the user

By default, this user will have null values for it's properties. You'll need to fetch the user (by username) if you want to populate it with data. The two following lines do the same thing:

<?php
$user->findByUsername('ccornutt');
$user->find(array('username'=>'ccornutt');
?>

If the user is found, it populates the object with the data returned from the API.

You can also use the User object to get all of the users on your account:

<?php
$userList = $user->findAll();
?>

If you'd like to get the Phone records associated with the User, you can call the getPhones method:

<?php
$phones = $user->getPhones();
?>

If the user has already been populated, it will return the phones already on the account. If not, you can use the first parameter to give a user ID (not username) to fetch for:

<?php
$phones = $user->getPhones('user-id-string');
?>

Validation on User

One of the main features of the API is to be able to validate the codes that the user has inputted to ensure they're correct. To do this, you can call the validateCode method on an already fetched User:

<?php
$user = new \DuoAuth\User();
$user->findByUsername('ccornutt');
if ($user->validateCode($code) == true){
    echo 'Validated!';
}
?>

If you want to check to see if a user is valid and can even authenticate against your service, you can call the preauth method:

<?php
$user = new \DuoAuth\User();
if ($user->preauth('ccornutt') == true) {
    echo 'Valid user! Now try to validate the code...';
}
?>

Working with Devices

You can associate an already added device to a current user with the associateDevice method:

<?php
$user = new \DuoAuth\User();
$phone = new \DuoAuth\Device\Phone();
$phone->findById('phone-internal-id');
$user->findByUsername('ccornutt');
$user->associateDevice($phone);

// or you can unassociate it the same way
$user->unassociateDevice($phone);
?>

Sending messaging to the user

There's a few different ways you can send messages to your users - either through a "push" to the client on their phones, via an SMS message or through an automated call.

Making a Call

The PIN will be automatically generated unless you specify it in the additional options. The default message is "Your valid PIN is " if not specified.

<?php
$user = new \DuoAuth\User();
$user->sendCall('2145551234');
// or with a custom message
$user->sendCall('2145551234', 'Howdy, your new PIN is <pin> pardner');
?>

Sending an SMS

The PIN will be automatically generated unless you specify it in the additional options. The default message is "Your valid PIN is " if not specified.

<?php
$user = new \DuoAuth\User();
$user->sendSMS('2145551234');
// or with a custom message
$user->sendSMS('2145551234', 'Howdy, your new PIN is <pin> pardner');
?>

Sending a Push

Sending a push requires the user to have the Duo Security app on their device. This is not for sending SMS messages to the user.

<?php
$user = new \DuoAuth\User();

// you can either find the user first...
$user->findByUsername('ccornutt');
$user->sendPush('phone-id-here');
?>

Adding Users to Account

Enrolling a User

The newer version of the Duo Security API allows for user enrollment directly. You can either specify a username or one will be made for you. The return value contains details about the created user:

<?php
$user = new \DuoAuth\User();
$newUser = $user->enroll('ccornutt1');
?>

Checking Enrollment Status

When a user is enrolled, they're sent as pending until they finish the verification process. To check on this status, you can use:

<?php
$user = new \DuoAuth\User();
$status = $user->getEnrollStatus($userId, $activationCode);
?>

NOTE: The userId and activationCode values above are pulled from the results of the enroll call. You can find the userId again with a find() call, but you must record the activation code.

Miscellaneous Functionality

Generating Bypass Codes

When you need to generate a set of bypass codes the user can use for validation when they can't get to their device, you can call this on the User object:

<?php
$user = new \DuoAuth\User();
$codes = $user->generateBypassCodes('ccornutt');
?>