No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
toxtli Merge pull request #4 from toxtli/master
CONFIG.md instructions were updated with the new Cloud Platform interface.
Latest commit 73d408f Apr 19, 2016
Permalink
Failed to load latest commit information.
bin New changes Apr 19, 2016
demos New changes Apr 19, 2016
src New changes Apr 19, 2016
.gitignore Initial commit Jun 20, 2015
CONFIG.md New changes Apr 19, 2016
CONTRIBUTING.txt Initial commit Jun 20, 2015
Icon New changes Apr 19, 2016
LICENSE.txt Initial commit Jun 20, 2015
README.md Initial commit Jun 20, 2015
config.properties Initial commit Jun 20, 2015
pom.xml Initial commit Jun 20, 2015

README.md

Account provisioning for Google Apps

Account provisioning for Google Apps is an open source API to:

  • Generate available usernames in your Google Apps domain
  • Create Google Apps accounts in your domain

It can be used in a website where users create their own accounts...

self account provisioning demo |

a script that creates accounts in bulk...

bulk account provisioning demo |

or via a CSV input...

csv input |

Usernames are generated automatically via configurable patterns. Sample images are taken from the included demos. Give them a try here!

This API can be installed as a RESTful service (to be invoked from almost any programming language and platform) or as a Java library.

Who should use it

Google Apps deployments where new usernames need to be created. Deployments that need to sync existing usernames can use [Google Apps Directory Sync] (https://support.google.com/a/answer/106368?hl=en) or [Google Apps School Directory Sync] (https://support.google.com/a/answer/6027781?hl=en).

Why you should use it

  • Username cache: It caches all your Google Apps accounts, which makes it fast (minimum calls to Google servers) and less likely to hit [Directory API calls/day limits] (https://developers.google.com/admin-sdk/directory/v1/limits)
  • Custom user fields: Usernames are generated from the user's first name, last name and a set of (optional) custom fields, i.e. second last name, student ID, department, nickname, etc.
  • Locked suggestions: Suggested usernames will remain locked (unavailable to other users) until they expire or are explicitly unlocked.
  • Backed by Google Apps Admin SDK: Uses the Google Apps [AdminSDK Directory API] (https://developers.google.com/admin-sdk/directory/)
  • SSL support: All REST calls can be encrypted using SSL
  • Any programming language: You can choose any programming language and platform that supports REST calls. Almost any language and platform do.

What methods does this API offer

  • suggest: returns a list of username suggestions based on first name, last name and a set of custom fields.
  • create: creates a Google Apps account.
  • select: unlocks username suggestions that will no longer be used.

See the API Overview section to learn more about how to invoke these methods.

Quick start

Ready? Try the demos!

This API needs Java, but don't worry you don't need to develop your client in Java. You can use any language and platform you like (Python, JavaScript, PHP, C#, ObjectiveC, Go, etc.) as long as it can do REST calls.

Included demos are built in JavaScript.

1. Check your Java version

In the terminal run:

java -version

If you see: java version "1.7.X" or a newer version you are ready to go. If not, install Java 7 or a newer verion.

2. Set your Google Apps domain configuration

Follow the steps in the Google Apps domain configuration guide to configure your domain to work with this API.

3. Start the RESTful API service

Move the config.properties and the p12 file (created in the previoius step) to the bin/ folder.

In the terminal, run:

java -jar appsProvisioning-0.0.1.jar -rest -port 8080

This will start the RESTful API service on port 8080. If you already have a server running on port 8080, change it to another port, e.g. 8888.

4. Open a demo

Awesome! You can now start getting usernames suggestions and creating Google Apps accounts in your domain.

See the Note below if you used a different port from 8080

Open any of the index.html demos under the demos/ folder:

Demo Sample
self-provisioning-demo
Each user selects and creates their own account
self account provisioning demo
bulk-provisioning-demo
All accounts are created in bulk
bulk account provisioning demo
csv-provisioning-demo
All accounts are created in bulk from a CSV input
csv demo

Note: If you used a different port from 8080, open first the JavaScript .js file inside the demo folder and update

var API_HOST = 'http://localhost:8080';

to point to the right port. For example:

var API_HOST = 'http://localhost:8888';

Both demos will initially show the configuration parameters that are relevant to the client. For example:

demo info

This screen will disappear after a couple of seconds.

You can change these parameters in the config.properties file and use this screen to verify the current configuration. Follow the next step to see how.

A quick way of testing your server is by invoking the suggest method via the GET service <a href="http://localhost:8080/rest/suggest?firstname=john&lastname=smith"target="_blank">http://localhost:8080/rest/suggest?firstname=john&lastname=smith

5. Play with the configuration

Now that you have the demos up and running is a great time to learn how usernames are generated.

  1. Open the config.properties file and look for the accounts.UsernameGeneration.patterns property.
  2. Replace its value with the following one:
accounts.UsernameGeneration.patterns=[C1_firstname].[lastname][custom1],[C3_lastname]_[custom1],[C1_custom1][firstname],[firstname][C1_lastname]_[custom1],[lastname][custom1]

Now kill the Java process (Ctrl+C or Cmd+C) in the terminal and start the RESTful API service again (step 3). This will load the new patterns configuration, which will result in different usernames being generated.

Open the self-provisioning-demo\index.html demo and notice how the generated usernames are now different. They now follow the new patterns set in the config file. The configuration section explains how to patterns work.

Next, you can try changing other accounts.UsernameGeneration properties. For example, updating the following properties:

accounts.UsernameGeneration.numberOfSuggestions=5

accounts.UsernameGeneration.suggestedUsernamesTimeout=10

This will result in:

  • 5 usernames being suggested (instead of 3)
  • usernames will expire after 10 seconds (instead of in 2 minutes)

Next steps

  • To learn more about other configuration properties (e.g. how to enable SSL in your server), take a look at the Configuration properties section.
  • To start changing the client side code, take a look at the API overview section.
  • To modify the server code side, take a look at the Contributing section.
  • If you have any questions or feedback, please let us know in the forum!

Index

System overview

This API is developed in Java and can be invoked from any language and platform that can do REST API calls. The username cache is an H2 database, so you will see a usernames(*).mv.db file when running the API.

use cases diagram

Only usernames are cached, no names or other user's data is ever stored. The H2 Console Application can be used to inspect the cache.

The cache can be disabled with the cachedUsernames property. When disabled it will do Admin SDK API calls. When enabled, the cache will refresh periodically (see the cacheExpirationHours property).

API overview and sample code

suggest method

Description: Method that suggests available usernames in a domain. Uses the configuration file (see configuration) to determine:

Note: All suggested usernames will remain locked until they expire (see suggestedUsernamesTimeout) or the select method is called.

| REST API | Java API | ------------ | ------------- | ---------------- Method | rest/suggest | apps.provisioning.server.account.UsernameManager.suggest Parameters | JSON map with the following fields:

  • firstname the user's first name
  • lastname the user's last name
The JSON map might include customizable fields. For example:
  • secondLastname
  • nickname
| userData: A java.util.HashMap<String, String>with the following fields:
  • firstname the user's first name
  • lastname the user's last name
The HashMap might include customizable fields. For example:
  • secondLastname
  • nickname
Returns | In case of success, it returns a JSON serialized array with username suggestions, in case of error it returns a JSON serialized map with the "errorMessage" index explaining the error. | A java.util.ArrayList<String> of suggestions. Throws an Exception in case of an error.


Sample code for suggest

REST API
var url = 'http://localhost:8080/rest/suggest';
var parameters = '{' +
    '"firstname": "Carlos",' +
    '"lastname": "Alvarez",' +
    '"secondLastname": "Martinez"' +
'}';
var xhr = new XMLHttpRequest();
xhr.onload = function() {
  alert(this.responseText);
};
xhr.open('POST', url, true);
xhr.send(parameters);
Java API
HashMap<String, String> userData = new HashMap<String, String>();
userData.put("firstname", "Carlos");
userData.put("lastname", "Álvarez");
userData.put("secondLastname", "Martinez");

ProvisioningApp provisioningApp = ProvisioningApp.getInstance();
provisioningApp.initApp();
UsernameManager usernameManager = provisioningApp.getUsernameManager();
ArrayList<String> suggestions = usernameManager.suggest(userData);

Result

["carlos.alvarez","carlosalvarez","c.alvarez_martinez"]

Note:

The following config.properties (see configuration) was used for this example:

...
patterns = [firstname].[lastname], [firstname][lastname], [C1_firstname].[lastname]_[secondLastname]
numberOfSuggestions = 3
...

select method

Description: Selects the given username from the given suggestions. This will unlock all the suggestions, except the selected one (if any).

| REST API | Java API | ------------ | ------------- | ---------------- Method | rest/select | apps.provisioning.server.account.UsernameManager.select Parameters | JSON map with the following fields:

  • username the selected username
  • suggestions a list of suggestions
|
  • suggestions an ArrayList<String> of suggested usernames
  • selectedUsername the selected username
Returns | In case of success, it returns a JSON serialized array with username suggestions, in case of error it returns a JSON serialized map with the "errorMessage" index explaining the error. | void
Throws an Exception if an error occurs.

Sample code for select

REST API
var url = 'http://localhost:8080/rest/select';
var parameters = '{"username":"carlos.alvarez", "suggestions":["carlos.alvarez","carlosalvarez","c.alvarez"]}';
var xhr = new XMLHttpRequest();
xhr.onload = function() {
  alert(this.responseText);
};
xhr.open('POST', url, true);
xhr.send(parameters);

Result

{"message":"User selected successfully."}
Java API
String selectedUsername = "carlos.alvarez";
ArrayList<String> suggestions = new ArrayList<String>();
suggestions.add("carlos.alvarez");
suggestions.add("carlosalvarez");
suggestions.add("c.alvarez");

ProvisioningApp provisioningApp = ProvisioningApp.getInstance();
provisioningApp.initApp();
UsernameManager usernameManager = provisioningApp.getUsernameManager();
usernameManager.select(suggestions, selectedUsername);

create method

Description: Creates a Google Apps account in the provided Google Apps Domain (see domain).

| REST API | Java API | ------------ | ------------- | ---------------- Method | rest/create | apps.provisioning.server.account.UsernameManager.create Parameters | JSON map with the following fields:

  • username account's username
  • firstname user's first name
  • lastname user's last name
  • password account's password
|
  • username account's username
  • firstname user's first name
  • lastname user's last name
  • password account's password
Returns | In case of success, it returns a JSON serialized array with username suggestions, in case of error it returns a JSON serialized map with the "errorMessage" index explaining the error. | void
Throws an Exception if an error occurs.

Username and password fields must comply with the [Google Apps Name and password guidelines] (https://support.google.com/a/answer/33386?hl=en)

Sample code for create

REST API
var url = 'http://localhost:8080/rest/create';
var parameters = '{"username":"carlos.alvarez", "firstname":"Carlos", "lastname":"Alvarez", "password":"12345678"}';
var xhr = new XMLHttpRequest();
xhr.onload = function() {
  alert(this.responseText);
};
xhr.open('POST', url, true);
xhr.send(parameters);

Result

{"message":"User created successfully."}
Java API
String username = "carlos.alvarez";
String firstname = "Carlos";
String lastname = "Alvarez";
String password = "12345678";

ProvisioningApp provisioningApp = ProvisioningApp.getInstance();
provisioningApp.initApp();
UsernameManager usernameManager = provisioningApp.getUsernameManager();
usernameManager.create(username, firstname, lastname, password);

API limits

Account provisioning for Google Apps follows the same [AdminSDK Directory API limits] (https://developers.google.com/admin-sdk/directory/v1/limits). Each call to create, select and suggest consumes a different number of Directory API calls:

Configuration properties

The configuration is set in the config.properties file. Configuration properties are divided in four categories:

  1. Username generation properties: use the property prefix accounts.UsernameGeneration.
  2. Google API properties: use the property prefix apis.GoogleAPIs.
  3. Cache location properties: use the property prefix db.h2.
  4. SSL properties: use the property prefix security.ssl.

Username generation properties

accounts.UsernameGeneration.cachedUsernames

Description: A username cache can be used to check if a username already exists. This prevents reaching AdminSDK API calls/day limit. If cachedUsernames is set to YES username availability will be checked against the cache. If set to NO it will be checked against the Google Directory (using a Directory API call).

Possible values: YES and NO


accounts.UsernameGeneration.cacheExpirationHours

Description: Defines the expiration time in hours of the usernames cache. After expiration, the application refreshes the username cache. For reference, refreshing an account with 1 million users takes approximately 35 minutes.

Possible values: Integers larger or equal to 1

Default: 24


accounts.UsernameGeneration.numberOfSuggestions

Description: The number of username suggestions to be returned for each call to suggest.

Possible values: Integer between 1 and 10 (inclusive)

Default: 3


accounts.UsernameGeneration.suggestedUsernamesTimeout

Description: The amount of time (in seconds) that suggested usernames will remain locked (unavailable to another client).

Possible values: Integer greater than 0.

Default: 120 (2 minutes)


accounts.UsernameGeneration.patterns

Description: A pattern is something that looks like [firstname][lastname]. This pattern indicates the API that we want to generate a username with "the firstname followed by the lastname". Now, if that username happens to be taken the API will need another pattern. Therefore, a list of multiple patterns is recommended. For example:

accounts.UsernameGeneration.patterns=[firstname][lastname],[lastname][firstname]

This will first try to generate a username with "the firstname followed by the lastname" if that is taken then it will try to generate a username with "the lastname followed by the firstname".

So far so good?

Great. Now, say we want to generate a username with "the nickname followed by the lastname" of a person. We'd simply do:

accounts.UsernameGeneration.patterns=[nickname][lastname]

What's [nickname] you might ask?

Well, nickname is a field that should be passed to the suggest method. For example:

var parameters = '{' +
    '"firstname": "Jonathan",' +
    '"lastname": "Bravo",' +
    '"nickname": "Jonny"' +
'}';

This will generate the username jonnybravo.

NOTE:

  • It is not mandatory to pass nickname (or any custom field) for all users. If nickname is not provided for a user the API will skip that pattern and move on to the next one.
  • firstname and lastname are mandatory. Even if the pattern doesn't make use of them.

Taking the first char(acters) of a field

Now say that for someone named John Smith we'd like to generate a username jsmith. We'd do it with the following pattern:

[C1_firstname][lastname]

C1 indicates that the API should take the first character of firstname. If we'd like to take the first two characters then we'd do:

[C2_firstname][lastname]

This same method applies for custom fields. For example, if we wanted to split the first character of the nickname we'd do:

[C1_nickname]

Adding a counter to a pattern

Now, say we have so many people named "John Smith" in a school district that we ran out of patterns. We could then define a pattern that adds a number at the end of the username:

[firstname][lastname][#]

[#] indicates that a number will be added to the username. For example: johnsmith3. This numeric value will start at 1 and continue adding until a username is available.

Note: The use of [#] should be the last resort as this counter can become hard to remember, e.g. johnsmith3816. A list of multiple patterns without [#] is encouraged before using a pattern with [#].

Adding separators to usernames

A common practice is to separate usernames with a period (.), an underscore (_) or a dash (-). These separators can be added to patterns. Example:

[firstname].[lastname]

would generate the username john.smith

Adding a string to a pattern

Same as the separators, it is possible to add a static string to username suggestions. For example, the pattern:

[lastname]_nyc

would generate the username smith_nyc

What if the API runs out of patterns?

The following pattern is used as the last resort:

[C9_firstname][C9_lastname][#]

patterns example


Given the following user data map, customFields and patterns: ```json { "firstname": "Carlos", "lastname": "Álvarez", "region": "CA", "group": "5A" } ```
patterns = [firstname].[lastname], [C1_firstname].[lastname], [firstname][lastname]_[region], [firstname][lastname]_[group], [lastname]_nyc, [firstname][lastname][#]

Then consecutive calls to the suggest method will return (in that order):

Generated username Used pattern
carlos.alvarez [firstname].[lastname]
c.alvarez [C1_firstname].[lastname]
carlosalvarez_mx [firstname][lastname]_[region]
carlosalvarez_5A [firstname][lastname]_[group]
alvarez_nyc [lastname]_nyc
carlosalvarez1 [firstname][lastname][#]
carlosalvarez2 [firstname][lastname][#]
carlosalvarez3 [firstname][lastname][#]
... [firstname][lastname][#]

Notes:

  • Special characters (e.g accents) are removed
  • All text gets converted to lowercase
  • Using a [#] will ignore the following patterns (as it will continue increasing the counter)


Google API properties

Follow the steps in the Google Apps domain configuration guide to configure these properties.

apis.GoogleAPIs.domain

Description: The Google Apps domain

Example: apis.GoogleAPIs.domain=yourdomain.com


apis.GoogleAPIs.authUser

Description: Admin user who created the project in the Google Developer Console.

Example: apis.GoogleAPIs.authUser=admin@yourdomain.com


apis.GoogleAPIs.keyPath

Description: Path to the file that stores the Google private key. Can be generated following the steps in: https://cloud.google.com/storage/docs/authentication#service_accounts

Example: apis.GoogleAPIs.keyPath=./service_account_key.p12


apis.GoogleAPIs.serviceAccountEmail

Description: Internal user for server side applications. Can be generated following the steps in: https://cloud.google.com/storage/docs/authentication#service_accounts

Note: You should enable API scopes in the Google Admin Console. This scopes can be registered following the steps in: https://support.google.com/a/answer/162106?hl=en

The following scope to the service account should be added: https://www.googleapis.com/auth/admin.directory.user

Example: apis.GoogleAPIs.serviceAccountEmail=1234567890123-abcdefghijklmnopqrstuvwxz01234567@developer.gserviceaccount.com


apis.GoogleAPIs.appName

Description: This value is the project name in the Google Developer Console. Can be obtained following the steps in: https://developers.google.com/console/help/new/#creatingdeletingprojects

Example: apis.GoogleAPIs.appName=My project



Cache location properties

db.h2.name

Description: The name of the H2 database .mv.db file.

Default: usernames


db.h2.path

Description: The path where the H2 database (.mv.db file) will be created.

Default: ./



SSL properties

security.ssl.useSSL

Description: Enables HTTPS support over SSL.

Possible values: YES and NO

Default: NO


security.ssl.keyStorePath

Description: The path where the KeyStore (jks file) is located. This can be generated executing:

keytool -genkey -alias sitename -keyalg RSA -keystore keystore.jks -keysize 2048

security.ssl.keyStorePassword

Description: The KeyStore password. Password provided when the jks file was generated.


security.ssl.keyManagerPassword

Description: Commonly the same as keyStorePassword. Can be different if it is not a self-generated certificate.

Building

Requirements

Build steps

To generate a appsProvisioning-0.0.1.jar file under ./target:

From bash

From the project's root folder, run:

mvn clean install -Dmaven.test.skip=true

From Eclipse

  1. Right click on the project
  2. Run As > Maven build...
  • Under Goals: use clean install
  • Check the Skip test checkbox

Note: Tests create and remove Google Apps accounts in a test domain. Therefore, they are discouraged unless you plan to submit a change that affects those tests.

Feedback

If you have any questions or feedback, please let us know in the forum!

Impressions

This API logs the number of calls to suggest, create and select per Google Apps domain. No other information is ever collected. This helps us justify adding more resources and support to this API.

License

Account provisioning for Google Apps is licensed under Apache 2.0. Full license text is available in the LICENSE file.

This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.

Contributing

See CONTRIBUTING.

A good starting point to look at the Java code is

apps.provisioning.server.rest.ProvisioningAction

you can navigate through each of the methods: suggest, select and create.