IAM in Service Catalog
This guide describes the Groups Web Service (GWS) REST API as used by programmatic clients. It does not describe the user interface offer to browser users.
The GWS REST API is a programmable interface, so you are expected to be an application developer. Your application must be able to connect to the web service using HTTPS and authenticate using SSL/TLS authentication with an X.509 certificate. It must be able to make HTTP GET, PUT, and DELETE requests to the service as needed.
The GWS offers a "RESTful" programmatic interface. It exposes groups and group information as addressable resources via the uniform HTTP interface; authorized clients may retrieve (GET), update (PUT) and delete (DELETE) representations of these resources through our REST API. Some notes:
Clients authenticate with X.509 certificates issued by the UW Services Certificate Authority and are identified by the Subject of the certificate: specifically, the DNS name included in the Common Name (CN) value or any Subject Alt Names.
Hosts connecting to the GWS must have their DNS name registered in UW DNS.
The GWS also identifies itself with a server certificate issued by the same authority.
Some clients may assume the privileges of, and act for, another user. This is accomplished by adding an act-as header to a request:
Clients are encouraged to connect on the alternate port (7443), as it requests certificate authentication on the initial SSL negotiation. Connecting to port 443 works, but your client will have to be able to handle renegotiation of the connection. Also note that jumbo frames (MTU > 1500) are not supported.
A group may be configured to require 2-factor authentication for update operations including PUT and DELETE operations on the general information, membership, or application information.
authnfactor" and has a value of
However, note that:
2cannot be updated via the API.
The API attribute class is "
classification" and may have the values:
Direct Members: Groups have several types of direct members:
A simple UWNetID, e.g.
A fully qualified eduPersonPrincipalName, e.g.
A UWCA certificate's common name or subjectAltName, e.g.
Name of another group, e.g.
|UWWI||A UWWI machine name|
March 27, 2019 – Groups Service API v3 is recommended for production use. v3 includes JSON and has Swagger documentation.
|Table of Contents|
Version 2 supports the authnfactor, classification, membership dependency (dependson), and optin and optout ACLS.
If you are making large membership changes, say more than a few hundred, your experience will be better if you split your activity into adds or deletes of fifty to a hundred members at a time. This tends to give you immediate feedback on successful changes and avoids possible session or connection timeouts.
Warning: This use of POST is deprecated and will not be supported in future API versions.
The Groups v2 API accepts the POST method for two purposes:
URI too long.
If your uri would be too long for likely transport to the web service you may enclose it in a POST, with the elements:
included in the POST document. The path components of you actual URL must match those in the posted "_uri".
PUT content too big
If your PUT content would be too big for likely transport to the web service you may enclose it in a POST, with the element:
included in the POST document.
text}" should be replaced with a specific name or identifier.
GWS supports version v1 and v2. Version 2 supports the authnfactor, classification, membership dependency (dependson), and optin and optout ACLS.
API customers can find the new v3 JSON documentation: https://wiki.cac.washington.edu/display/infra/Group+Service+v3+API
Email email@example.com to contact the staff in UW-IT who oversee this wiki space and the groups service.
Announcements : Join firstname.lastname@example.org for service announcements.
Discussion : Discuss the service with other customers and users on email@example.com.