Who this information is for
This page gives technical details of how to authenticate users by implementing Open ID Connect (OIDC) using the University of Cambridge’s Microsoft Entra ID (formerly Azure Active Directory). This allows vendors and developers to use a standard authentication flow for web pages and applications.
Entra ID authentication replaces ucam-webauth, which has been deprecated. All systems using the ucam-webauth protocol need to migrate to using Entra ID for authentication instead. Using Entra ID allows you to authenticate both regular CRSids plus Alumni CRSids.
What is OpenID Connect (OIDC)
OIDC is a relatively new protocol built on top of OAuth2 and is designed with modern web pages and apps in mind. OIDC provides JSON web tokens that contain relevant claims regarding the authentication request.
Claims are name and value pairs that contains information about a user along with meta information about the OIDC service. This information is encoded into the web token.
Implementing OIDC using Entra ID at the University of Cambridge is reasonably straightforward, especially for developers familiar with OAuth2.0 as OIDC is an extension of this protocol.
Migrating from ucam-webauth to OIDC in Entra ID
OIDC in Entra ID has more features and more users available to developers compared to ucam-webauth.
Ucam-webauth is a simple authentication protocol that provides a 'Yes' or 'No' response. OIDC can provide pieces of data about the authenticated user called 'claims'.
Claims
Claims are pieces of information about a user returned as part of the authentication to Entra ID.
When an application registration is created via Toolkit, Toolkit configures it to return the following claims:
- First name
- Last name
- UPN (User name)
We encourage developers to query Entra ID for user attributes. If additional attributes are required, please contact the UIS Service Desk stating the application ID and the attributes you want returned.
Users in Entra ID
Users in Entra ID include:
- Alumni
- Readers - visitors to the University Libraries
- Guests - users external to the University who have been granted access to some data in the University's Office 365 tenancy
Systems authenticating against Entra ID must perform some kind of authorisation check.
Understanding identities in Entra ID
When you start with Entra ID, you might assume that all identities are of the form <CRSid>@cam.ac.uk.This is not the case.
There are identities in Entra ID that:
- look nothing like a CRSid at the start
- do not end in cam.ac.uk
- belong to people who are not part of the University of Cambridge
Application developers must treat the username as an opaque string because of these variations.
An Entra ID identity says nothing about the status of the user. You must not assume a user authenticated by Entra ID is a member of staff or a student at Cambridge or one of its colleges. You must use other APIs to get information about a user. For example, separately interrogating Entra ID for group membership of a user.
In Entra ID terminology, the username is called the User Principal Name (UPN). Refer to Microsoft's documentation for more in-depth information.
User Groups
The claims returned for a user includes a list of groups. We do not allow all the groups a user is a member of to be returned in the group claim as this could easily exceed the maximum permitted size of the response. We encourage developers to query Entra ID direct for a user's group memberships.
Application registrations created by Toolkit are configured to return a subset of groups for which the user is a member. This subset can be used to make decisions about an identity. Refer to the Toolkit documentation for more information.
If your application needs a different set of groups returned in the claim, please contact the UIS Service Desk stating the application ID and the list of groups (either full group name or group ID) you would like returned.
Get started With OIDC
To set up any application to use Entra ID for authentication, you need several key pieces of information.
- Tenant ID. This is a GUID that uniquely identifies an Office 365 Entra ID. The Tenant ID for the University's Entra ID is 49a50445-bdfa-4b79-ade3-547b4f3986e9
- Client ID. This uniquely identifies your application within Entra ID. In Entra ID, your application can be given certain rights. By default, an application will only be allowed to authenticate a user and obtain minimal information about the user.
- Client Secret. This is linked to the Client ID and can be thought of as a “password” for the Client ID.
- The Redirect URI. This is the link to the OpenID client in your application. It must be on a different path to anything in your application. Unless the URI refers to localhost, the Redirect URI must use the HTTPS scheme.
For libraries that are Entra ID aware, they tend to put the username in a field clearly labelled as something like “username”. For more generic OIDC libraries, Entra ID returns the UPN in a field called “upn”.