Gateway Service OIDC Protocol Integration

Introduction

Integration process in brief:

  1. Create Enterprise Directory group for your developer team
  2. Create a Developer Team via the Developer web app
  3. Create an app for the team
  4. Register O-Protocol endpoint

More detailed instructions can be found here: https://gateway.login.vt.edu/docs/api.html

Identity Providers

Currently, only the VT Login service can be used for authenticating users. Social providers may be included in future releases.

Supported Services

Currently, only VT-hosted services/apps can integrate with Gateway. Specifically, redirect URIs MUST be in the vt.edu domain namespace.

Single Logout

Tokens issued by Gateway are NOT included in single logout requests. Instead, clients must use the Gateway token revocation endpoints for revoking tokens. See the Gateway API docs.

Scopes - Attribute Release

Note that the scope is the value a relying party would use when calling the Gateway /oauth2/authorize endpoint. This value generally aligns with the Enterprise Directory attribute name, but does differ in some instances.

Note: All /oauth2/authorize requests MUST include the openid scope.

Default Scopes

The following scopes (person attributes) are default released to Virginia Tech apps.

Scope ED Attribute Description
name displayName Preferred display name, typically First M Last
given_name givenName First name
groupMembershipUugid groupMembershipUugid Group name (uugid) of ED groups to which user belongs
email mailPreferredAddress Preferred Email
middle_name middleName Middle name
family_name sn Surname (last name)
targetedMembership N/A Targeted group membership for a person
virginiaTechAffiliation virginiaTechAffiliation A user’s relationship to VT

All Supported Scopes

Scope ED Attribute Description
address address List of addresses know for a person
bannerName bannerName The banner name of this person
birthdate dateOfBirth A person’s date of birth
c c Office address 2 letter country code
campus campus Name of the campus this person is currently affiliated with
college college College name
cn cn List of formatted names
creationDate creationDate Date added to directory
department department The home department this person works in on campus
departmentNumber departmentNumber Employee numerical department ID
email mailPreferredAddress Preferred email
email_verified N/A Email verification flag (true for @vt emails)
facsimileTelephoneNumber facsimileTelephoneNumber Office fax number
family_name sn Surname (last name)
gender gender Reported gender
given_name givenName First name
groupMembershipUugid groupMembershipUugid Group name (uugid) of ED groups to which user belongs
homePhone homePhone Home phone
homePostalAddress homePostalAddress Home mailing address
initials initials Initials of a persons name
instantMessagingID instantMessagingID List of IM IDs
l l Office address locality (e.g. Blacksburg)
labeledURI labeledURI Webpages associated with a person
lastEnrollmentTerm lastEnrollmentTerm Human readable: Last academic term a student was enrolled
localPhone localPhone Local phone number
localPostalAddress localPostalAddress Local mailing address
mail mail List of email addresses
mailExternalAddress mailExternalAddress This is a person’s external email address
mailStop mailStop Internal mail routing information
major major Academic major
middle_name middleName Middle name
mobile mobile Collection of mobile phone numbers
name displayName Preferred display name, typically First M Last
nextEnrollmentTerm nextEnrollmentTerm Human readable: Next academic term a student is enrolled
pager pager Collection of pager numbers
personType personType Type of person (VT, Sponsored, Guest)
pidm bannerPIDM 8 digit PIDM from banner
postalAddress postalAddress Office mailing address(es)
postalCode postalCode Office postal code(s)
postOfficeBox postOfficeBox Office PO Box
st st Office address state abbreviation
street street Office street address
studentLevelCode studentLevelCode Student level code (e.g. UG)
suppressDisplay suppressDisplay If person’s entire record is suppressed
suppressedAttribute suppressedAttribute Suppressed attributes for a person
targetedMembership N/A Targeted group membership for a person
telephoneNumber telephoneNumber Office telephone number
title title Person working title
udcIdentifier udcIdentifier The Banner UDC Identifier
uid uid A unique numerical value representing a person
userCertificate userCertificate A user’s X.509 certificate
userSMIMECertificate userSMIMECertificate X.509 certificate specifically for use in S/MIME applications
uupid uupid Universally unique personal identifier
virginiaTechAffiliation virginiaTechAffiliation A user’s relationship to VT
virginiaTechID virginiaTechID 9 digit Virginia Tech ID number from Banner

Groups for Authorization

The following two scopes are intended to provide group membership data to support authorization in apps:

  1. groupMembershipUugid - names of all groups to which the authenticated user belongs
  2. targetedMembership - names of groups to which the authenticated user belongs that the app has registered interest in

In general targetedMembership should be preferred as it limits the payload of data delivered to the app to those groups that are relevant to application behavior. While it requires some additional effort to configure, namely using the “Targeted Groups” configuration panel in App Manager to register groups of interest, it tends to be a one-time configuration concern that provides a long-term performance benefit to applications. Apps should register all substrings of groups it wants to consume.

The groupMembershipUugid attribute also requires some configuration in order for Gateway to see groups, but requires configuration on the group rather than the destination app. The mw-gateway service MUST be added as a service viewer to any groups that are intended to be consumed by Gateway and forwarded on to apps. Note that this requirement does not apply to the targetedMembership attribute, which has special handling to overcome the traditional security model of service viewership applied to groups.