PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

---

Parent package: Foswiki::LoginManager
Child packages:

More ...Less ...

Foswiki::LoginManager::SamlLogin

This provides a LoginManager which can authenticate using Saml, while still providing access to the underlying TemplateLogin manager.

ClassMethod new($session)

Construct the object

ObjectMethod loadSamlData()

Given a provider key which must reference a key in the Foswiki configuration under Extensions->Saml, loads relevant provider information into object properties.

ObjectMethod extractEmail($attributes) → $email

Given a Saml attributes, tries to find an e-mail claim and returns it. Currently this is rather dumb; it should be made more intelligent.

ObjectMethod extractLoginname($nameid) → $loginname

This extracts a Foswiki loginname from a id token. Which claim is used as the login name ultimately depends on the attribute configured in Foswiki::cfg.

ObjectMethod buildWikiName($attributes) → $wikiname

Given the Saml attributes, builds a wikiname from it. Which attributes are used to build the wikiname ultimately depends on the Foswiki::cfg settings. If the wikiname that's built ends in ...Group or is contained in the list of forbidden WikiNames, WikiGuest (or rather, the configured default WikiName) is returned instead.

ObjectMethod matchWikiUser($wikiname, $email) → $wikiname

This checks whether the e-mail address stored in a WikiName topic's form field matches the $email argument. If it does, then the name of the topic (e.g. the $wikiname) is returned. If it doesn't, undef is returned. The wikiname is also returned when the WikiName topic doesn't exist or pre-assigning wikinames is disabled in the configuration.

ObjectMethod _isAlreadyMapped($session, $loginname, $wikiname) → $boolean

This is an internal helper function which tries to determine whether a given loginname is already mapped to a wikiname or not. Unfortunately, there doesn't seem to be a "right" way to determine this while staying inside the constraints of the public API.

ObjectMethod mapUser($session, $attributes, $nameid) → $cuid

This handles the mapping of a loginname as extracted from the SamlResponse to a WikiName. We don't keep a mapping ourselves; we simply instruct the configured UserMapper to create one if it doesn't exist yet. If the UserMapper doesn't create a permanent mapping, we'll go through the same motions again when the user authenticates the next time. Much of the code here is concerned with trying to make sure that WikiNames which were pre-assigned aren't used in a mapping by mistake before the actual user authenticates and claims the WikiName. We also handle duplicate names by increasing a counter to generate WikiName2, WikiName3, WikiName4 etc.

ObjectMethod redirectToProvider($request_url, $query, $session)

This is called directly by login() and is responsible for building the redirect url to the Saml provider. It generates the redirect and sends it back to the user agent.

ObjectMethod samlLogout($saml_response, $query, $session)

This is called directly by login() when login() detects a successful Logout response from the Saml provider. When we get here, we have SAML response that needs to be decoded.

ObjectMethod samlCallback($saml_response, $query, $session)

This is called directly by login() when login() detects a successful callback from the Saml provider. When we get here, we have SAML response that needs to be and decoder for user information. Verify that the response was related to the request the issuer and the id from the Saml Authnreq must be sent to the Assertion->valid() probably a better way to track the id/inresponseto

ObjectMethod _LOGOUTURL ($thisl)

ObjectMethod loginUrl () → $loginUrl

Overrides LoginManager. Content of a login link.

ObjectMethod logoutUrl ()

Provides a NatSkinPlugin supported logoutUrl to return a URL for the logout action

ObjectMethod _logoutUrl () → $_logoutUrl

Internal function to generate the SAML logout URL. The user's logout action calls the bin/login?saml=logout generated by logoutUrl and the login script calls this function to generate the SAML LogoutRequest URL

ObjectMethod login($query, $session)

The login method now acts as a switchboard. There are basically two different uses of the login method.

First, it is used by the user agent to get a login page. We detect this case by looking for the absence of all parameters or for a provider=native parameter. The native provider is used to display the original TemplateLogin page; in that case, this login() method simply hands the query and session on to it's parent.

Second, it is used as a callback url by an Saml provider. We detect this case by looking for state, code or error parameters.

There is one more case: When the provider parameter is provided, we do an oauth redirect to the given provider.

ObjectMethod getMetadata()

This is called directly by login() when login() detects a request for Foswiki's metadata. This will generate a metadata.xml file for download. This is also called by the Configure Wizard in configure

StaticMethod setUserFields ($session, $user, @emails)