cas-auth

Authenticates users against a CAS server.

Category AuthenticationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin cas-authPriority 2597

What it does

cas-auth signs people in at a CAS server before their browser reaches the route's backend. The people live on the CAS server at IdP URI, not on a consumer. The server sends the browser back to the CAS callback URI, and the gateway answers that path and the Logout URI itself, so both have to be paths the route serves.

A browser without a session is answered 302 and sent to the CAS server's sign-in page. Authentication explains callers who sign in at an identity provider.

When to use it

• Staff or students open an internal web application behind the gateway, and their accounts are kept on the organisation's CAS server.
• A backend that has no sign-in of its own should be reached only by people who signed in at CAS first.
• People sign out of the application at one path of the route, which the gateway answers for them.

Not for an OpenID Connect provider or bearer tokens on API calls — see openid-connect (Authenticates users against an OpenID Connect provider), a SAML identity provider — see saml-auth (Authenticates users with a SAML identity provider) or a directory name and password a program sends on every call — see ldap-auth (Authenticates consumers against an LDAP directory).

Set it up

Send visitors to a CAS server to sign in before they reach the service

The callback and logout paths must be ones this route serves, since the gateway answers them itself.

Set IdP URI to https://cas.example.com/cas, set CAS callback URI to /cas/callback, set Logout URI to /cas/logout and fill Cookie as in the JSON below.

cas-auth · as the console saves it

{
  "idp_uri": "https://cas.example.com/cas",
  "cas_callback_uri": "/cas/callback",
  "logout_uri": "/cas/logout",
  "cookie": {
    "secret": "<secret>"
  }
}

Things to know

• IdP URI — A browser without a session is answered 302 with a Location that starts with this address and goes on with /login?service=.
• Logout URI — Only a GET on this path signs the reader out, and without a session cookie it answers 401. Other methods are handled as ordinary requests.
• Secret — This signs the short-lived cookie that remembers where the reader was going, and not the session the ticket is exchanged for.
• Secret — A secret shorter than 32 characters is refused when you save.
• SameSite — Only Lax and None can be set; Strict is refused when you save.
• Secure — Off together with SameSite None is refused when you save.
• AdviceRegister the CAS callback URI as an allowed service on the CAS server, and serve the route over HTTPS only.
• On a consumer or a consumer group it runs only after the consumer has been identified by a credential; it does not identify the consumer itself.

Settings

The fields as the console shows them, section by section.

IdP URIidp_uristringRequired

example https://cas.example.com/cas

CAS callback URIcas_callback_uristringRequired

Where the CAS server sends the browser back, such as https://gw.example.com/cas/callback. A bare path takes the gateway's own scheme, host and port. A full address is used as written.

Logout URIlogout_uristringRequired

CookiecookieobjectRequired

Secretcookie.secretstringRequired

A random string that signs the sign-in cookie. Stored on the engine and shown only to roles that manage this object.

at least 32 characters

SameSitecookie.samesitestringdefault Lax

one of Lax, None

Securecookie.securebooleandefault true

Request body limitmax_req_body_sizeintegerdefault 67108864

The largest single-logout message, in bytes, the CAS server may post to the callback path. A larger one is answered 400. No other request body is read.

at least 1

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.