Implementing SCIM APIs
"Automation is good, so long as you know exactly where to put the machine.”
- Eliyahu Goldratt
This article covers SCIM and the full implementation of the SCIM API within an integrated, event-driven user identity and provisioning solution that also leverages the Administration API.
SCIM (System for Cross-domain Identity Management) is a set of API calls that let you manage users in your organization. Typically, you would link these calls to changes in your identity store (e.g., Active Directory, or OpenLDAP). The SCIM calls add, update, or delete users – or more precisely user identities — to, in, or from your organization. The APIs give you full access and control of these user identities.
SCIM and Domain Organizations
A domain organization is a company identity you create and manage in the GoTo Central authentication service to manage sign in options for your users. The Organization lets you validate one or more company email domains, and lets you then enable users in those domains to use Single Sign-On protocols as authenticated users in that identity.
User and product access provisioning can be handled automatically by Identity and Access Management (IAM) providers or the GoTo Active Directory Connector tool or in a custom way using the SCIM and Administration APIs.
Implementing SCIM APIs versus Other Methods
As described above, the SCIM and Administration APIs are pre-built into some solutions as part of Enterprise Sign-On.
- For those accounts using a third party IAM provider, the IAM will call the SCIM APIs on your behalf as part of their solution. See the Enterprise Sign-On overview for more.
- For accounts using Active Directory, GoTo provides the Active Directory Connector (v1.6+) that will automatically add new users from your Active Directory and configure them with access to the desired products. When updates and deletions occur, the Active Directory Connector will synchronize those events with your Organization and account. (Contact Customer Care for the latest version of the ADC)
- When first configuring your Organization, you will likely want to associate all existing users in your account with that Organization. A tool called the SCIMHelper can assist with this one-time association. The Active Directory Connector guide includes documentation for the SCIMHelper.
API Authentication, Application Roles, and User Roles
In order develop against GoTo APIs, you will need at least one developer account. The account is free. Register at https://goto-developer.logmeininc.com/user/register
There are Getting Started instructions on the developer site. The following provides the specific entries and steps needed to make the user identity and provisioning calls successfully.
The developer APIs need credentials to access GoTo resources and data in your account: You will need to have an Account Admin login for your corporate GoTo account.
Create an App
In https://goto-developer.logmeininc.com, create an App.
- From the home page, click My Apps.
- Click Add a new app.
- Enter an App Name and Description. These can be anything you wish.
- Select GoToMeeting as the Product API (even if you have additional products).
- Set the Application URL to https://api.getgo.com.
Set App to Production Status
All new developer apps are created in test mode which limits the number of API calls you can make to 500 per day. You need to request the status update from the API support team via email. (There is no cost for production status.)
Send an e-mail to email@example.com with the following information from your new App:
- Application Name
- App Product: GoTo Meeting
- Application URL: https://api.getgo.com
- Estimated number of end users (a guess is fine)
The account ID you use to authenticate to the API (along with your consumerKey) must be an Organization Admin and an Account Admin in order to leverage the SCIM and Adminstration APIs to do user identity management and product access management.
Identity and Provisioning API Calls
Creating an event-based user management integration for your GoTo applications requires specific data outputs from your corporate identity store. When you add a user, for example, the user data and the groups they belong to provide the information needed to add the user’s identity to the organization, add the user to your corporate account, and correctly grant them with the desired product access. An update or delete in the identity store would provide the information needed to make the proper changes on the GoTo side.
Once a change is made in your identity store the same workflow should apply for the API calls. When a user create or update takes place, make the identity (SCIM) create and update calls first, then add that user identity to your account with the appropriate Create User and License User (Admin) calls. For deletions, you can either remove all product access, OR remove the user identity from your account, OR remove the user identity completely. See more below in the “delete a user section” for details on the impacts of various operations.
Below are some examples of common operations that you will need to perform and when to use the SCIM and Administration APIs to perform that operation. This is intended as an introduction to the API workflows. Prior to developing against the APIs, however, be sure to review the full API Reference documentation for both the SCIM APIs and Administration APIs to understand the methods available to you.
Create new user identity
The SCIM User Create API call adds a user identity to your organization within a verified domain. The existence of this identity does not provide the user access to products on its own, but must be followed with the appropriate Admin API calls as described below.
The call requires a user name and email. The password is optional, since the user may be authenticating to GoTo products via your SAML IdP. Only an organization admin can access the identity data and make changes to email, name, etc.
NOTE: If you “create” a user identity via SCIM where that user already has a user account, that user account will not be substantively changed. Instead, it will simply become associated to your Organization – meaning that the user can make use of your SAML IdP and cannot change their own e-mail address (as their identity is now owned by your organization).
See the SCIM API Reference
Grant product access to a user identity
After creating the user via the SCIM API, you would typically grant that user access to one or more products in your GoTo account. Use the Admin Create User API with the appropriate License Keys for the specific products the user is authorized for.
The user’s name and e-mail address in the Admin API Create User call must match those used in the initial SCIM API Create User call.
Upon success of the Admin API Create User call, the user will receive a Welcome e-mail informing them they have access to the selected products. The new user will need to set a password and sign-in to start using the product.
NOTE: If you want to create new user accounts with a default password, follow the instructions in the Forum entry, How to create a user with a default password.
Change a user’s email address
If a user’s e-mail address changes, a single SCIM Update User API call accomplishes this. After issuing this call, the user must use the new e-mail address when authenticating to GoTo products.
Change a user’s product access
In many cases, customers have implemented an events-based provisioning model where, for example, when a user is moved between security groups in their user directory (e.g. LDAP), they are given or removed from access to particular GoTo products.
In the event this occurs, you do not need to delete and recreate the user’s identity or even remove and re-add the user to your account. Instead, simply update the user’s product access using the License User and Unlicense User methods of the Admin API. It is possible to suppress e-mails to users in this case if desired.
Delete a user
In the event that a user has been removed or permanently disabled from your user identity store, you can remove that user from yourm account completely with a Delete User call in the SCIM API. A SCIM Delete User call will completely revoke all product access for a user and remove their GoTo identity - preventing them from logging into any GoTo service with their corporate e-mail address.
WARNING: Deleting a user via the SCIM API will also remove any product data attached to that user (such as scheduled meetings, meeting history, etc.). A user can be re-created, but the deleted data cannot be restored. If the desire is to retain this data, but prevent product access, the user can be removed from all products using the Admin Unlicense User API.