VUser:...g::V2_0(3pm)

📦
version 1.0.1 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

VUser::Google::Provisioning::V2_0 💖

okay so bestie, this is a page from the User Contributed Perl Documentation, section 3pm — aka your girl's here to walk you through VUser::Google::Provisioning::V2_0, which is the module that lets you talk to version 2.0 of the Google Provisioning API. buckle up. 🎀

✨ NAME ✨

VUser::Google::Provisioning::V2_0 — the support module for version 2.0 of the Google Provisioning API. that's it, that's the name, she's self-explanatory and iconic for it. 💅

🌸 SYNOPSIS 🌸

here's the whole vibe, copy-paste ready, no edits from me (obvi):

use VUser::Google::ApiProtocol::V2_0;
use VUser::Google::Provisioning::V2_0;

my $google = VUser::Google::ApiProtocol::V2_0->new(
    domain   => 'example.com',
    admin    => 'admin_user',
    password => 'secret',
);

my $api = VUser::Google::Provisioning::V2_0->new(
    google => $google,
);

## Create user
my $new_user = $api->CreateUser(
    userName    => 'fflintstone',
    givenName   => 'Fred',
    familyName  => 'Flintstone',
    password    => 'I<3Wilma',
);

## Retrieve a user
my $user = $api->RetrieveUser('fflintstone');

## Retrieve all userr
my @users = $api->RetrieveAllUsers();

## Update a user
my $updated = $api->UpdateUser(
    userName   => 'fflintstone',
    givenName  => 'Fredrock',
    familyName => 'FlintStone',
    suspended  => 1,
    quota      => 2048,
);

## Change password
$updated = $api->ChangePassword('fflintstone', 'new-pass');

$updated = $api->ChangePassword(
    'fflintstone',
    '51eea05d46317fadd5cad6787a8f562be90b4446',
    'SHA-1',
);

$updated = $api->ChangePassword(
    'fflintstone',
    'd27117a019717502efe307d110f5eb3d',
    'MD5',
);

## Delete a user
my $rc = $api->DeleteUser('fflintstone');

(yes, ## Retrieve all userr is spelled exactly like that in the original and I am not touching it, that typo is canon now 🫶)

🦋 DESCRIPTION 🦋

so VUser::Google::Provisioning::V2_0 provides support for managing users using version 2.0 of the Google Provisioning API. that's the whole job. managing users. she's a people manager fr fr. 👑

to actually use the Google Provisioning API, you must turn on API support from the Google Apps for Your Domain control panel. and the user you use to create the VUser::Google::ApiProtocol object must have administrative privileges on the domain. no admin, no entry. 🚫

Note: it's a really good idea to log into the web control panel at least once as the API user, so you can accept the the terms of service and admin terms. if you don't, you'll get intermittent authentication errors when you try to use the API. and intermittent errors are the actual worst, like the most annoying genre of bug, literally 😭

💜 METHODS 💜

unless it says otherwise, these methods will die() if there is an API error. so like, wrap them in eval or Try::Tiny or whatever your little heart desires, bestie.

CreateUser

CreateUser() takes a hash of create options and returns a VUser::Google::Provisioning::UserEntry object if the account was created. CreateUser() will die() if there is an error. (yes she's dramatic, she said what she said.)

the keys of the hash are:

  • userName (required) — the user name of the account to create
  • givenName (required) — the user's given name
  • familyName (required) — the user's family name
  • password (required) — the user's password. if hashFunctionName is also set, this is the base16-encoded hash of the password. otherwise, this is the user's plaintext password.
    • Google required that passwords be, at least, six characters. six! minimum! don't be out here with abc 💀
  • hashFunctionName — must be SHA-1 or MD5. if this is set, password is the base16-encoded password hash.
  • quota — the user's quota in MB.
    • not all domains will be allowed to set users' quotas. if that's the case, creation will still succeed but the quota will be set to the default for your domain. so like, it just shrugs and does its own thing 🙈
  • changePasswordAtNextLogin — if set to a true value, e.g. 1, the user will be required to change their password the next time they login in. this is the default. you may turn this off by setting changePasswordAtNextLogin to 0.
  • admin — if set to a true value, e.g. 1, the user will be granted administrative privileges. a false value, e.g. 0, admin rights will be revoked. by default, users will not be granted admin rights.

RetrieveUser

my $user = $api->RetrieveUser('fflintstone');

retrieves a specified user by the user name. RetieveUser will return a VUser::Google::Provisioning::UserEntry if the user exists and undef if it doesn't. (that RetieveUser spelling? also straight from the source. we love her. we protect her. ✨)

RetrieveUsers

my @users = ();

my %results = $api->RetrieveUsers();
@users = @{ $results{entries} };

while ($results{next}) {
    %results = $api->RetrieveUsers($results{next});
    push @users, @{ $results{entries} };
}

fetches one page of users starting at a given user name. currently, a page is defined as 100 users. this is useful if you plan on paginating the results yourself or if you have a very large number of users. like, thousands. a whole army. 🫡

the returned result is a hash with the following keys:

  • entries — a list reference containing the user accounts. each entry is a VUser::Google::Provisioning::UserEntry object.
  • next — the user name for the start of the next page. this will be undefined ("undef") if there are no more pages.

see RetrieveAllUsers() if you want to fetch all of the accounts at once. 🎀

RetrievePageOfUsers

this is a synonym for RetrieveUsers(). same girl, different name, lowkey iconic. 💅

RetrieveAllUsers

my @users = $api->RetrieveAllUsers();

get a list of all the users for the domain. the entries in the list are VUser::Google::Provisioning::UserEntry objects. all of them. every single one. no cap. 🔥

UpdateUser

my $updated = $api->UpdateUser(
    userName  => 'fflintstone',
    givenName => 'Fred',
    # ... other options
);

updates an account. UpdateUser takes the same options as CreateUser() but only userName is required.

UpdateUser() cannot be used to rename an account. see RenameUser(). don't try it, she will not do it, it's not a her-problem, it's a you-problem.

RenameUser

my $user_user = $api->RenameUser($oldname, $newname);

rename an account. the first parameter is the old user name; the second is the new user name. RenameUser() will die if the old name does not exist. so like, make sure she exists first, bestie 😭

DeleteUser

my $rc = $api->DeleteUser('fflintstone');

deletes a given user. returns true if the delete succeded and dies if there was an error. gone. deleted. unfollowed. blocked. ✨

ChangePassword

$updated = $api->ChangePassword('fflintstone', 'new-pass');

$updated = $api->ChangePassword(
    'fflintstone',
    '51eea05d46317fadd5cad6787a8f562be90b4446',
    'SHA-1',
);

$updated = $api->ChangePassword(
    'fflintstone',
    'd27117a019717502efe307d110f5eb3d',
    'MD5',
);

change a users password. 🔐

ChangePassword takes the user name, password and, optionally, a hash function name. if the hash function name is set, the password is the base16-encoded password, otherwise it is the clear text password.

accepted values for the has function name are MD5 and SHA-1. (again: has is exactly what the original says, I'm just the messenger 🧚)

there is no difference between using this and using UpdateUser to change the user's password. same result, different entrance. main character energy either way. 👑

🌈 SEE ALSO 🌈

(that stray item * is literally sitting there in the original, bestie, and I am nothing if not faithful 💖)

💀 BUGS 💀

bugs may be reported at http://code.google.com/p/vuser/issues/list. go tell them, they want to know, they're listening, fr fr. 🐛

👑 AUTHOR 👑

Randy Smith <perlstalker@vuser.org> — the icon, the legend, the moment. 🫶

Copyright (C) 2009 Randall Smith

this program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU General Public License for more details.

you should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

so like, in summary: it's free, it's GPL, and if it breaks your stuff, that's between you and the universe. periodt.

and that's the whole page, bestie!! this one was generated by perl v5.32.0 and dated 2021-01-09, so it's giving slightly vintage but still absolutely serving. slay, go provision some users, and don't forget to log into that control panel first. mwah 💋✨🌸

📦 where this page comes from