WebSSO / Entra ID

Northwestern users authenticate via single sign-on. The starter supports two SSO providers through the northwestern-sysdev/laravel-soa package’s WebSSOAuthentication trait.

Providers:

• Microsoft Entra ID (formerly Azure AD) - OAuth2 authorization code flow directly to Microsoft
• Online Passport (agentless WebSSO) - Cookie-based SSO via OpenAM/ForgeRock, validated through Apigee

The starter auto-detects which provider to use based on your credentials. If WEBSSO_API_KEY is set or WEBSSO_STRATEGY is forgerock-direct, login/logout routes through Online Passport. Otherwise, it defaults to Entra ID. Only one provider is active at a time.

For a higher-level overview of all authentication methods, see the Authentication documentation.

How It Works (Entra ID)

1. User clicks “Sign in with NetID”

   The application redirects to Microsoft’s login endpoint via WebSSOController@oauthRedirect. The OAuth2 authorization code flow goes directly to login.microsoftonline.com, not through Apigee or ForgeRock.

2. User authenticates with Microsoft

   User enters their credentials.

3. Callback with token

   Microsoft redirects back to /auth/azure-ad/callback via POST with an authorization code. CSRF middleware is excluded for this route since the request originates from the identity provider. The laravel-soa package exchanges the code for tokens and validates the ID token JWT using Microsoft’s signing keys.

4. Directory Search lookup

   WebSSOController::findUserByNetID() calls FindOrUpdateUserFromDirectory to provision or update the user from Northwestern’s directory. This includes a 3-attempt retry with 500ms delays. If all retries fail, a 503 error page is rendered.

5. Session established

   The authenticated() hook regenerates the session and CSRF token, creates a UserLoginRecord for audit purposes, and logs the user in.

How It Works (Online Passport)

1. User clicks “Sign in with NetID”

   The application redirects to ForgeRock’s login page via WebSSOController@login. The user is sent to Northwestern’s Online Passport login portal.

2. User authenticates with ForgeRock

   User enters their NetID credentials (and completes MFA if Duo is enabled).

3. Cookie validation

   After authentication, ForgeRock sets a nusso session cookie. The laravel-soa package validates this cookie by calling Northwestern’s agentless WebSSO API (via Apigee or directly against ForgeRock, depending on the configured strategy).

4. Directory Search lookup

   WebSSOController::findUserByNetID() calls FindOrUpdateUserFromDirectory to provision or update the user, identical to the Entra ID flow.

5. Session established

   The authenticated() hook regenerates the session and CSRF token, creates a UserLoginRecord for audit purposes, and logs the user in.

---

Routes

Entra ID Routes

Method	URI	Controller	Name
GET	/auth/azure-ad/redirect	WebSSOController@oauthRedirect	login-oauth-redirect
POST	/auth/azure-ad/callback	WebSSOController@oauthCallback	login-oauth-callback
GET	/auth/azure-ad/oauth-logout	WebSSOController@oauthLogout	login-oauth-logout

Online Passport Routes

Method	URI	Controller	Name
GET	/auth/websso/login	WebSSOController@login	login-websso
GET	/auth/websso/logout	WebSSOController@logout	login-websso-logout

---

Logout

Entra ID Logout

The oauthLogout() method handles SSO session cleanup:

• Production - Delegates to the laravel-soa trait’s oauthLogout() method, redirecting to Entra ID’s logout endpoint. The local session is cleared afterward.
• CI environment - Skips the Entra redirect and performs a local-only logout to avoid external service dependencies.

Online Passport Logout

The logout() method (from the WebSSOAuthentication trait) redirects the user to ForgeRock’s logout endpoint to clear the nusso session cookie. The local session is invalidated before the redirect.

---

Error Handling

If the Directory Search lookup fails after 3 retries during the SSO callback, the controller throws a ServiceDownError identifying the DIRECTORY_SEARCH service. The application’s exception handler renders a user-facing 503 page rather than exposing a stack trace.

---

Entra ID Configuration

Environment Variables

#AZURE_CLIENT_ID Required

Entra ID application client ID

#AZURE_CLIENT_SECRET Required

Entra ID application client secret

#AZURE_REDIRECT_URI Required

OAuth callback URL

Tip

Entra ID requires registering the application in Azure’s control panel. You’ll need to generate a client ID and secret, and register the callback URI. The callback must use HTTPS.

---

Online Passport Configuration

Setting WEBSSO_API_KEY (or using WEBSSO_STRATEGY=forgerock-direct) switches the starter from Entra ID to Online Passport. The login and logout buttons will automatically route through ForgeRock instead of Microsoft.

Environment Variables

#WEBSSO_STRATEGY apigee

SSO strategy (apigee or forgerock-direct)

#WEBSSO_URL_BASE https://uat-nusso.it.northwestern.edu

ForgeRock base URL

#WEBSSO_API_URL_BASE https://northwestern-prod.apigee.net/agentless-websso

Agentless WebSSO API URL (Apigee)

#WEBSSO_API_KEY Required

Apigee API key for agentless WebSSO

#WEBSSO_REALM northwestern

WebSSO realm

#WEBSSO_COOKIE_NAME nusso

WebSSO session cookie name

#DUO_ENABLED false

Enable Duo MFA (sets auth tree to ldap-and-duo)

Note

The apigee strategy routes ForgeRock cookie validation through Northwestern’s Apigee gateway. The forgerock-direct strategy validates cookies directly against the ForgeRock server. Both are for the Online Passport flow; Entra ID does not use either strategy.

See the laravel-soa documentation for full details on configuring Online Passport.