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...
a script that creates accounts in bulk...
or via a 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.
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).
- 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.
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.
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.
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.
Follow the steps in the Google Apps domain configuration guide to configure your domain to work with this API.
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.
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:
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:
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
Now that you have the demos up and running is a great time to learn how usernames are generated.
- Open the
config.properties
file and look for theaccounts.UsernameGeneration.patterns
property. - 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)
- 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!
- System overview
- API overview and sample code
- Configuration properties
- Building
- Feedback
- License
- Contributing
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.
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).
Description: Method that suggests available usernames in a domain. Uses the configuration file (see configuration) to determine:
- Number of suggested usernames:
numberofsuggestions
- Patterns used to generates usernames:
patterns
- Google Apps Domain:
domain
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 namelastname
the user's last name
secondLastname
nickname
userData
: A java.util.HashMap<String, String>
with the following fields: firstname
the user's first namelastname
the user's last name
secondLastname
nickname
"errorMessage"
index explaining the error. | A java.util.ArrayList<String>
of suggestions. Throws an Exception
in case of an error.
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);
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
...
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 usernamesuggestions
a list of suggestions
suggestions
anArrayList<String>
of suggested usernamesselectedUsername
the selected username
"errorMessage"
index explaining the error. | void
Throws an
Exception
if an error occurs.
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."}
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);
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 usernamefirstname
user's first namelastname
user's last namepassword
account's password
username
account's usernamefirstname
user's first namelastname
user's last namepassword
account's password
"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)
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."}
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);
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:
create
: 1 API callselect
: 0 API callssuggest
:- cache enabled (
cachedUsernames=YES
): 0 API calls - cache disabled (
cachedUsernames=NO
): number of API calls is equal or larger than thenumberOfSuggestions
property
The configuration is set in the config.properties
file. Configuration properties are divided in four categories:
- Username generation properties: use the property prefix
accounts.UsernameGeneration.
- Google API properties: use the property prefix
apis.GoogleAPIs.
- Cache location properties: use the property prefix
db.h2.
- SSL properties: use the property prefix
security.ssl.
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
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
Description: The number of username suggestions to be returned for each call to suggest
.
Possible values: Integer between 1 and 10 (inclusive)
Default: 3
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)
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. Ifnickname
is not provided for a user the API will skip that pattern and move on to the next one. firstname
andlastname
are mandatory. Even if the pattern doesn't make use of them.
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]
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 [#].
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
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
The following pattern is used as the last resort:
[C9_firstname][C9_lastname][#]
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)
Follow the steps in the Google Apps domain configuration guide to configure these properties.
Description: The Google Apps domain
Example: apis.GoogleAPIs.domain=yourdomain.com
Description: Admin user who created the project in the Google Developer Console.
Example: [email protected]
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
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
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
Description: The name of the H2 database .mv.db
file.
Default: usernames
Description: The path where the H2 database (.mv.db
file) will be created.
Default: ./
Description: Enables HTTPS support over SSL.
Possible values: YES
and NO
Default: NO
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
Description: The KeyStore password. Password provided when the jks
file was generated.
Description: Commonly the same as keyStorePassword
. Can be different if it is not a self-generated certificate.
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
- Right click on the project
- 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.
If you have any questions or feedback, please let us know in the forum!
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.
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.
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
.
account-provisioning-for-google-apps's People
Forkers
paulsisler rafiuskes toxtli kleopatra999 insightsdev-stg genesiswhat marcelobrgomes davidmoritz sawon1234 caioy3k jrchou thaingo yannixiang neotim isabella232 test-mass-forker-org-1 ghas-results bohdansecaccount-provisioning-for-google-apps's Issues
Security Policy violation Binary Artifacts
This issue was automatically created by Allstar.
Security Policy Violation
Project is out of compliance with Binary Artifacts policy: binaries present in source code
Rule Description
Binary Artifacts are an increased security risk in your repository. Binary artifacts cannot be reviewed, allowing the introduction of possibly obsolete or maliciously subverted executables. For more information see the Security Scorecards Documentation for Binary Artifacts.
Remediation Steps
To remediate, remove the generated executable artifacts from the repository.
Artifacts Found
- bin/appsProvisioning-0.0.1.jar
Additional Information
This policy is drawn from Security Scorecards, which is a tool that scores a project's adherence to security best practices. You may wish to run a Scorecards scan directly on this repository for more details.
Allstar has been installed on all Google managed GitHub orgs. Policies are gradually being rolled out and enforced by the GOSST and OSPO teams. Learn more at http://go/allstar
This issue will auto resolve when the policy is in compliance.
Issue created by Allstar. See https://github.com/ossf/allstar/ for more information. For questions specific to the repository, please contact the owner or maintainer.
There is a vulnerability in Jetty: Java based HTTP/1.x, HTTP/2, Servlet, WebSocket Server 9.2.3.v20140905,upgrade recommended
CVE-2017-7658 CVE-2017-7657 CVE-2017-9735
Recommended upgrade version:
9.3.29.v20201019
Adding a delete option
It will be useful, if one is using the application in a "test mode". By using delete one can delete the users they created in the previous "test" run.
Hello
Cristy
Sql injection
The suggestGet method in the ProvisioningAction.java accepts the parameters in the request and puts them into "userDataMap".
Finally, participated in the database interaction in the executeQuery() method in H2DataSource.java.
An attacker can perform a SQL injection attack by constructing malicious parameters -- "lastanme" and "firstname".
Updating javascript files to ES6 standard
In order to go along with the current standards, I think it would be wise to re-factor JavaScript files according to the new ES6 standards.
Google account
Updating Documentation for New Developer Console
The instructions to create the client ID, email and p12 key don't match the new developer console.
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.