This module deals with the Google OpenID Connect federated authentication method. An HTTP handler that wishes to establish a login using Google uses the following flow of control.

• Call oauth_authenticate/3. This predicates redirects to Google, which in turn redirects to oath2(auth_redirect), implemented by oauth_handle_redirect/1.
• The predicate oauth_handle_redirect/1 establishes the Google unique user identification (a string holding large integer) and email. It calls the multifile hook google_client:login_existing_user/1, which logs in the user (e.g., by starting an HTTP session and associating the user with the session) and replies with a web page (or redirect).
• If google_client:login_existing_user/1 fails, this library fetches user profile information from Google and calls the hook google_client:create_user/1. The create_user hook is passed the basic Google profile information. Its task is to create a new user.

See also

- https://developers.google.com/accounts/docs/OpenIDConnect

 oauth_authenticate(+Request, +Site, +Options)

Step 2: redirect to Google for obtaining an authorization code. Google redirects back to oauth_handle_response/1. Options:

realm(+Realm)

Value for openid.realm. Normally, this is the site's root URL. By default, it is not sent.

login_hint(+Hint)

Hint to select the right account. Typically an email address. By default, it is not sent.

client_data(+Data)

Add the given Data (any Prolog term) to the dict that is passed to the login hooks.

 openid_connect_discover(+Site, -Dict) is det

True when Dicr represents The Discovery document.

 key(+Which, -Key) is det[multifile]

This hook must provide the Google API keys. Key is one of the values below. The keys are obtained from Google as explained in https://developers.google.com/+/web/signin/add-button

• client_id
• client_secret

 login_existing_user(+Claim) is semidet[multifile]

Called after establishing the identify of the logged in user. Claim is a dict containing

sub:string

String that uniquely indentifies the user inside Google.

email:string

Email address of the user.

client_data:Term

Present if oauth_authenticate/3 was called with the option client_data(Term). Note that the term passed is a copy.

This call must return an HTML document indicating that the user logged in successfully or redirect to the URL supplied with return to using http_redirect/3.

 create_user(+Profile) is det[multifile]

Called after login_existing_user/1 fails and the Google profile for the user has been fetched. Contains the same info as passed to login_existing_user/1 as well as additional profile information such as family_name, gender, given_name, locale, name, picture and profile. Check the Google docs for details.

This call creates a new user, typically after verifying that the user is human and completing the profile. As login_existing_user/1, it must return a web page or redirect.

 cert_verify(SSL, ProblemCert, AllCerts, FirstCert, Error) is det

Used by SSL to verify the certificate.