From d5309ac51413d8ed74956545765180583055beae Mon Sep 17 00:00:00 2001 From: Roland Hedberg Date: Mon, 15 Dec 2014 08:32:43 +0100 Subject: [PATCH] Updated documentation. --- doc/howto/op.rst | 34 ++++++++++++++++++++++------------ doc/howto/rp.rst | 4 +--- 2 files changed, 23 insertions(+), 15 deletions(-) diff --git a/doc/howto/op.rst b/doc/howto/op.rst index 922b4b8..f41abd8 100644 --- a/doc/howto/op.rst +++ b/doc/howto/op.rst @@ -16,22 +16,32 @@ An OP provides a couple of endpoints to which RPs can send requests. Authentication -------------- -In general any authentication method can be used as long as the class implementing it includes the following interface: - * Inherit from `oic.utils.authn.user.UserAuthnMethod` - * Override `UserAuthnMethod.__call__`: should return a HTTP response containing either the login page - (see the simple username/password login authentication class `UsernamePasswordMako`) or a redirect - to a login page hosted elsewhere (see the SAML authentication class `SAMLAuthnMethod`). - * Override `UserAuthnMethod.verify`: should verify the authentication parameters from the associated login - page (served by `__call__`). Must return a tuple `(a, b)` where `a` is a HTTP Response (most likely 200 OK +In general any authentication method can be used as long as the class implementing +it includes the following interface: + + * Inherit from :py:class:`oic.utils.authn.user.UserAuthnMethod` + * Override :py:meth:`oic.utils.authn.user.UserAuthnMethod.__call__`: should + return a HTTP response containing either the login page + (see the simple username/password login authentication + class :py:class:`oic.utils.authn.user.UsernamePasswordMako` ) or a redirect + to a login page hosted elsewhere (see the SAML + authentication class :py:class:`oic.utils.authn.user.SAMLAuthnMethod`). + * Override :py:meth:`oic.utils.authn.user.UserAuthnMethod.verify`: should verify + the authentication parameters from the associated login + page (served by :py:meth:`oic.utils.authn.user.UserAuthMethod.__call__`). + Must return a tuple `(a, b)` where `a` is a HTTP Response (most likely 200 OK or a redirect to collect more information necessary to authenticate) and `b` is a boolean value indicating whether the authentication is complete. - The input to `verify` will contain any cookies received. If the authentication is part of a multi auth chain, - see below, the cookie returned by - `UserAuthnMethod.get_multi_auth_cookie` should be used to retrieve the original query from the RP. + The input to :py:meth:`verify` will contain any cookies received. If the + authentication is part of a multi auth chain, see below, the cookie returned + by :py:meth:`oic.utils.authn.user.UserAuthnMethod.get_multi_auth_cookie` + should be used to retrieve the original query from the RP. -To properly register the implemented verify method as the callback function at an endpoint of the OP, use -`oic.utils.authn.authn_context.make_auth_verify` (which wraps the specified callback to properly parse the request +To properly register the implemented verify method as the callback function at +an endpoint of the OP, +use :py:meth:`oic.utils.authn.authn_context.make_auth_verify` +(which wraps the specified callback to properly parse the request before it is passed along and handles the case of multi auth chains, see below). diff --git a/doc/howto/rp.rst b/doc/howto/rp.rst index 298b1ae..bd1f12a 100644 --- a/doc/howto/rp.rst +++ b/doc/howto/rp.rst @@ -29,10 +29,8 @@ Client class because it will provide interfaces to all of them. So lets start with instantiating a client:: from oic.oic import Client - c = Client() - The first choices is really not yours it's the OpenID Connect Provider (OP) that has to decide on whether it supports dynamic provider information gathering and/or dynamic client registration. @@ -59,10 +57,10 @@ probably the e-mail address syntax. It's something the looks like an e-mail address (local@domain) but not necessarily is one. At this point in time let us assume that you will instantiated a OIDC RP. + .. Note::Oh, by the way I will probably alternate between talking about the RP and the client, don't get caught up on that, they are the same thing. - As stated above depending on depending on the OP and the return_type you will use some of these steps may be left out or replaced with an out-of-band process.