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::OpenIDConnectLogin

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

ClassMethod new($session)

Construct the object

ObjectMethod loadProviderData($provider)

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

ObjectMethod serializedState() → $encoded_state

This returns the url-encoded state, which currently only consists of a random nonce value. If no state exists, a random value is generated.

ObjectMethod extractEmail($id_token) → $email

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

ObjectMethod extractCenter($id_token) → $center

Given a id token, tries to find an center claim and returns it

ObjectMethod extractFirstName($id_token) → $firstName

Given a id token, tries to find a given_name claim and returns it

ObjectMethod extractLastName($id_token) → $lastName

Given a id token, tries to find a family_name claim and returns it

ObjectMethod extractFullName($id_token) → $fullName

Given a id token, tries to find a name claim and returns it

ObjectMethod extractLoginname($id_token) → $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(id_token) → $wikiname

Given a id token, builds a wikiname from it. Which claims 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, $email, $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, id_token) → $cuid

This handles the mapping of a loginname as extracted from an id token 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($provider, $query, $session)

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

ObjectMethod oauthCallback($code, $state, $query, $session)

This is called directly by login() when login() detects a successful callback from the Open ID provider. When we get here, we have an authorization code and state and can now exchange it for an id token.

ObjectMethod displayLoginTemplate($query, $session)

Called by login() when it doesn't know what else to do. This displays the openid login template, which is currently hardcoded, so it can't be overwritten or reconfigured by a UserMapper.

Fair amounts of code are copied from the TemplateLogin login() method. Code readability would profit from refactoring TemplateLogin a bit...

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 Open ID 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.