Google Workspace Provision Accounts

About Google Workspace Provisioning Accounts

Through an application programming interface (API), Campus Cafe can request that accounts (usernames and passwords) be created in Google Workspace when created in Campus Cafe.

The API supports creating users associated with as many as four Campus Cafe permission groups. The common use case is to create accounts for applicants, students, alumni and parents based on their Campus Cafe permission groups, however, any four groups could be configured for use.

Within the four groups, the API supports directing them to different Google organizations, including a specific organization for users under the age 18. That group may restrict those users from certain Google services for compliance with rules regarding adolescents. 

Each time a Campus Cafe user has a permission group assigned or changed, the API will attempt to create an account in Google Workspace provided the user is being associated with an eligible permission group and does not already exist in Google Workspace. The API checks for the existence of the user by matching the user's Campus Cafe ID number to the Google Workspace Employee ID.

Prerequisites

Complete the Google Workspace SAML setup

Configure Google Workspace

Create Service Account User

This account will be used to authorize the connection between Campus Cafe and Google Workspace. Campus Cafe recommends creating a service user not tied to a specific individual. Refer to Google's documentation for creating an account.

Create Project

1. Navigate to https://console.cloud.google.com/home/dashboard
2. Click Create Project
3. Enter a Project name (e.g. CampusCafe), select the organization in which to apply the connection and a location in which to apply the connection.
4. Click Create

Create service account for project

1. Go to Google Cloud Platform
2. From Menu go to IAM & Admin>Service Accounts
3. Select Campus Café Project (if not already displaying)
4. Click ‘Create Service Account’
5. Set name to CampusCafe
6. Save, Done
7. Edit service account just created
8. Show Domain-Wide Delegation
9. Check ‘Enable G Suite Domain-wide Delegation’
10. Save

Create key for service account

1. Actions>Create key
2. Select Key type of JSON
3. Save key to safe place (You will need values from this key when configuring Campus Cafe)

Activate API for use project

1. Go to Google Cloud Platform
2. Menu>API & Services>Dashboard
3. Click on link ‘+ENABLE APIS AND SERVICES’
4. Find Admin SDK under category G Suite
5. Click panel and then click enable button

Authorize service account to use API

1. Copy Client ID from service account (click View Client ID link)
2. Go to https://admin.google.com
3. Menu>Security>API controls
4. Click ‘MANAGE DOMAIN WIDE DELEGATION’
5. Add new
6. Paste Client ID from Service account
7. Set Scopes to: https://www.googleapis.com/auth/admin.directory.user
8. Save

Configure Campus Cafe

Set Username Format

Campus Cafe will create a username for applicants following a naming convention specified.

1. Navigate to Admin > Custom Control Maintenance
2. Locate ProgramID SYUSUNAME 
3. Next to SYUSUNAME Sequence 1, Parameter 1 click the pencil
4. In Parameter 1 enter a value to determine the username naming convention. If a username already exists, the system will following the pattern and append a 01, 02, 03, etc.
   [empty/blank] = username will be first character of first name + last name
   L = Username will be last name + first character of first name
   I = Username will be Campus Cafe ID number
   LUF = Username will be last name underscore first name
   FUL = Username will be first name underscore last name
   FIMIL = Username will be first initial + middle initial + last name
   FDL = Username will be first name period last name
   FL = Username will be first name
   NL = Username will be first character of nickname + last name
   NDL = Username will be nickname period last name
5. Click Save

Set Password Format

Campus Cafe will assign a default password to the user, which will be passed to Google. Once the Google account is created, the user should change the password in Google, not Campus Cafe.

1. Navigate to Admin > Custom Control Maintenance 
2. Locate ProgramID SYUSPASS
3. Next to SYUSPASS Sequence 1, Parameter 7, click the pencil
4. Set Parameter 7 to Y to activate Parameters 8 and 9
5. In Parameter 8 enter a value to determine the default password
   1. [empty/blank] = password set to person's ID number, or
   2. S = password set to person's last four digits of their Social Security number + date of birth (Date of Birth format is CCYYMMDD)
6. To prepend the password with a fixed set of characters/numbers/symbols, enter that string in Parameter Value 9. This is useful if your SSO requires certain password complexity rules and you wish to ensure each password meets those rules. For example, if "Pie" is entered in Parameter Value 9 and Parameter Value 8 is set to S the user's password would be Pie123420200510 where Pie is the prefix, 1234 is the user's last four digits of their SSN and 20200510 represents the person's birthday.
7. In Parameter Value 6 enter Y to force the individual to log in using single sign on
8. Click Save

Domains

The Campus Cafe API supports single and multiple domains.

Set default domain 

This option is for institutions that utilize only one domain. The domain will automatically append to a username when the username is authenticated through SSO. It will not be appended to the actual username itself.

1. Navigate to Admin > Web App Config 
2. Locate Parameter LOGIN_UPN_DOMAIN
3. In the Value box enter @ and then the domain name (for example @myschool.edu)

Set domain manually

When created manually, a domain can be included in the username itself. This always takes precedence over any automated rules.

1. Navigate to Admin > Permission Maintenance
2. Click Lookup Person
3. Look up the individual to assign a username
4. In the username box enter the username including the domain
5. Click Save

The domain field can also be updated manually. 

If you want domain to be part of the username field, the following option will append a domain to username at time username is created by the system.
SYUSSTMAIL in  1-4 enter a Y if you want the domain (value in SYUSSTMAIL-1-4 ) to be appended to the username. Enter N if using multiple domains or you do not wish the domain to be appended. 

System managed domains

This option is for institutions that have multiple domains. Using the 4 org unit maps (GOOGLE_ORG_UNIT_ALUM, GOOGLE_ORG_UNIT_PARENT, GOOGLE_ORG_UNIT_PROSPECT, GOOGLE_ORG_UNIT_STUDENT) in Web App Config you can supply a default domain for each mapping. The default domain field will be updated in Campus Cafe automatically as a user's permission group changes. A change to the domain in this case will also change the primary email in google. Mapped domains will only be changed if the existing domain is a valid mapped domain.

Campus Cafe Permission Group - Google Org Unit mappings

There are 4 mappings (GOOGLE_ORG_UNIT_ALUM, GOOGLE_ORG_UNIT_PARENT, GOOGLE_ORG_UNIT_PROSPECT, GOOGLE_ORG_UNIT_STUDENT ) defined by the Connection Web App Configurations. The mappings allow you to specify which Campus Cafe groups map to Google org units. When a user's group permission in Campus Cafe is changed to one of these mapped values, it will cause Campus Cafe to check the user account in Google to see that it exists and has the mapped org unit. If the account does not exist, it is created in Google. If it exists but the org unit does not match the mapped org unit, then the org unit in Google is changed.

Connection Web App Configuration

1. Navigate to admin > Web App Config
2. In the Search box enter Google
3. Configure the below parameters 

Configure automated email to notify student of their username and password upon successful provisioning

1. Custom Control WEBCRDEML (Admin Menu -> Custom Control)
   1. WEBCRDEML Sequence 1, Parameter 1 controls whether or not the system will send an automated, mergeable email to the student to notify them of their username, password (created in SYUSPASS 1:7-9) and the login URL for the SSO login.  Setting WEBCRDEML 1:1 to Y, in conjunction with Web App value SSO_PROVISIONING_EMAIL_ADDRESS (see below) allows the email to go out. 
   2. WEBCRDEML 1:2 defines a support email contact that can be merged into the body of the notification email for login questions.
2.  Web App SSO_PROVISIONING_EMAIL_ADDRESS (Admin Menu -> Web App)
   1. SSO_PROVISIONING_EMAIL_ADDRESS is the email address that will send out the automated email. This value must be set for the email to send. The email will not send, even if WEBCRDEML 1:1 = Y.
3. Adjustable Text SSO_PROVISIONING_EMAIL_BODY (Admin Menu -> Adjustable Text)
   1. SSO_PROVISIONING_EMAIL_BODY is an HTML ready value that defines the body of the email that can be sent out. It accepts mergefields to the body of the email:
      1. [[LOGIN_URL]] - this is hard-coded as https://ABC-web.scansoftware.com/cafeweb/loginsso (where ABC is the 3-character code for your institution's Campus Cafe url)
      2. [[USERNAME]] - this is taken from the database value for the user
      3. [[PASSWORD]] - this defined by SYUSPASS 1:8 and 1:9
      4.  [[CONTACT_EMAIL]] - this is defined by Custom Control WEBCRDEML 1:2