Single Sign-on

There are several different options available for AS to do single-sign on.

Type	Typical Use Cases	Technology
ForgeRock OpenAM Integration	Agentless SSO, Agent SSO	OIDC/OAuth2 or OpenAM's bespoke REST APIs
Fed (Shibboleth)	SaaS Logins	SAML
Microsoft Entra ID	General purpose	OIDC/OAuth2 or SAML

All of these options support multifactor (MFA) authentication. MFA must be enabled for all applications as per the Admin Systems Expectations given over the last few years.

Recommendation

Entra ID is our preferred solution. When building custom applications, Entra ID OpenID Connect (OIDC) should be used. When integrating with vendor'd products, Entra ID OIDC or SAML should be used, if possible.

OIDC offers several flows suitable for traditional web apps, single-page apps (SPAs) without a backend, machine-to-machine integrations, and even device flows for authenticating limited-input devices like TVs.

Entra ID offers capabilities like managing authorization from the Azure console, logging, and customizing what data is included with the netID.

However, the decision should be done on an app-by-app basis. Look for circumstances that would require you to use another option:

• Items linked from authenticated NUInfo pages (the main northwestern.edu web server) use the OpenAM agent. If they link to another app using OpenAM, they have the same SSO session, and login is seamless. If the app used Entra ID, it is not the same login session as OpenAM, and the user may need to log in twice: once for the informational NUInfo page, and once when they click the link and visit the app.
• Shibboleth ingests metadata from other universities & institutions, so something meant to allow logins from peer organizations may have a huge ops burden on Entra ID's SAML vs. Shibb.

In the absence of circumstances that require a specific option, default to choosing Entra ID.

Microsoft Entra ID

Microsoft Entra ID (formerly Azure AD) is Azure's cloud identity solution. Cyberinfrastructure's Collaboration Services have replicated all of our identities to Entra, it can be used in a similar fashion to OpenAM.

As an added bonus, authenticating to Entra ID yields an access token that can call the Microsoft Graph API. This can be used to load the user's profile picture & detailed contact information. If additional scopes are set up and the user consents, it can be used to integrate with their Outlook calendar or other O365 services.

App Registrations

The cloud resource you will be working with is an "app registration": this is meant to be a single logical entity that holds data like the app's name, its OIDC callback URLs, and the client ID/secret. Users may need to "consent" to having the app process their personal information.

Most settings for an app registration are self-service. When you create a registration, you are the "owner" by default. It is recommended that you add other members of the team as owners.

To enable Duo MFA for your app registration, you must submit a ticket to the Cyberinfrastructure Collab Services team. MFA can only be enabled by Azure tenant administrators, and its enabled/disabled status is not reflected in your application's configuration dashboard.

The app registration may be configured to only allow logins for users it has been assigned to via group membership. This enables basic control over authorization from the Entra ID console (or the Self-Service Group Management tool).

The "claims" for an app registration are the data included with the netID. For OIDC, this is data that is included in the JWT that Entra ID hands to the application during login. Basic information is included, but you may add things like the user's AD groups. For SAML, this information is included in the SAML response.

Group Claim

Entra ID cannot include more than 50 groups in the claim.

It is recommended that you specify which group(s) are relevant, so Entra ID can return only that list. Otherwise, the list may be truncated at random and not include important group information.

There is also a way to create "permissions" in the app registration and map them to group memberships, but AS had not explored this functionality.

Applications via OpenID Connect

To use Entra ID's OpenID authentication, your application must be served via HTTPS, with an exception given for localhost.

You can log in to the Azure console and register an application to begin using OpenID authentication from the App registrations screen.

You will need to configure your application's redirect URIs on its Authentication screen, create a secret on its Certificates & secrets screen, and get the client ID from the Overview screen.

Since OpenID connect is a standard protocol built on OAuth2, your development framework is likely to have a plugin that supports it. For Laravel, the laravel-soa package includes a Socialite driver that will work with Northwestern's Entra ID tenant out of the box.

If you cannot find an existing integration library or plugin, review Microsoft's OpenID documentation on how to implement the authentication flow.

When possible, you should configure applications with an additional parameter for the authorization redirect: domain_hint=northwestern.edu. This will skip the initial "enter your microsoft account" screen and sends the user directly to the Online Passport netID login screen.

Secret Management

For web applications, the proper OpenID auth flow requires calling the /tokens endpoint and using a client secret.

The client secret expires after a set period of time. Azure will not notify users when their secrets are about to expire, so please make a note of this expiration and migrate to a new secret before an old one expires.

Single-page apps, mobile apps, and certain other applications use other flows that do not require this secret. Please choose an appropriate flow for your type of application.

OpenID with an ALB

If your app is using an ALB, you can configure a listener rule that will handle OpenID authentication for all requests, before the request is passed to your app:

resource "aws_lb_listener" "front_end" {
  load_balancer_arn = aws_lb.front_end.arn

  # . . . other config

  default_action {
    type = "authenticate-oidc"

    authenticate_oidc {
      client_id              = "your-client-id-here"
      client_secret          = "your-client-secret-here"
      authorization_endpoint = "https://login.microsoftonline.com/northwestern.edu/oauth2/v2.0/authorize"
      token_endpoint         = "https://login.microsoftonline.com/northwestern.edu/oauth2/v2.0/token"
      issuer                 = "https://login.microsoftonline.com/7d76d361-8277-4708-a477-64e8366cd1bc/v2.0"
      user_info_endpoint     = "https://graph.microsoft.com/oidc/userinfo"

      authentication_request_extra_params = {
          domain_hint = "northwestern.edu"
      }
    }
  }

  # . . . other actions
}

The redirect URI for the load balancer's OpenID provider is https://<your-app-hostname>/oauth2/idpresponse. Add this to the list of redirect URIs in the Entra ID console.

The forwarded request will include some additional headers with auth information. To obtain the netID from this, you will need to parse the JWT and pull out the userPrincipalName claim.

When using this approach, you should give consideration to how you will authenticate to your app when running it on your development machine.

Enterprise Applications via SAML

Entra ID has another class of application: enterprise applications. Entra ID will serve as a SAML IdP, similar to federation.

To get started with this, you must submit a ticket to Cyberinfrastructure's Collab Services group. They must do the Entra ID-side configuration. It should otherwise be similar to setting up federation.

OpenAM

This is the traditional "online passport" login screen that Northwestern has used for years.

There are two methods of doing an OpenAM integration: agentless SSO, which utilizes the nusso session cookie, or OAuth2. The web agent that Identity Services/Cyberinfrastructure provide for webservers like Apache and IIS utilizes OAuth2.

Agentless

Agentless SSO utilizes the nusso session cookie set for the .northwestern.edu domain. This cookie is httpOnly & secure, meaning that an application must meet all the following criteria to access the cookie:

• Served from a northwestern.edu name
• Served over HTTPS
• Has a backend that can access the cookie (client-side JavaScript cannot read the value of an httpOnly cookie)

The session token can be looked up using the Agentless SSO API and resolved to a netID. Depending on the authentication tree you use, you can trigger Duo MFA. The API endpoint will indicate whether an nusso session token has gone through MFA.

This is largely self-service. Requests for access to the Agentless SSO API are made in the API Service Registry and still must be reviewed and approved.

This is not a standard authentication protocol, so you will need to develop it in your application or use one of our agentless libraries. The APIs themselves are not following any standard (like OIDC) and are subject to change by the vendor. They are unlikely to change them, and the "agentless API" wrapper gives NUIT an opportunity to mitigate small changes and preserve compatibility for API consumers, but there is a risk.

Web Agent

The web agent comes in two flavours: the Apache agent for use on Linux, and the IIS agent for use on Windows Server. This is a package that Identity Services provides to CI that includes a config file that's been pre-configured with an OAuth2 client ID & secret.

If you want to use a web agent, you will need to submit a ticket to Identity Services asking them to set up a new application and provide the appropriate agent package for your webserver.

The web agent cannot be used with any serverless services on AWS. It could potentially be used with ECS Fargate, but we do not have any example Dockerfiles at this time.

Fed/Shibboleth

Federation (colloquially known as "fed" or "shibb") is a SAML identity provider (IdP). SAML is a standard that many enterprise SaaS service providers can work with.

To set up a SAML integration, you will need to get the service provider's SAML metadata and open a ticket to the Identity Services team. They will do the necessary configuration and provide you with the IdP's SAML metadata. Then, you can configure the SAML authentication on the SaaS app side.