Updated doc.

Author: rohe

chrp/example_conf.py

@@ -215,6 +215,35 @@
             'AccessToken': {},
             'UserInfo': {}
         },
+    },
+    'pingfed': {
+        "issuer": "https://pf.example.com/",
+        'client_id': 'pyrp_client',
+        'client_secret': 'someSecretxxx',
+        "redirect_uris": ["{}/authz_cb/pingfed".format(BASEURL)],
+        "behaviour": {
+            "response_types": ["code"],
+            "scope": ["openid", "profile", "email"],
+            "token_endpoint_auth_method": "client_secret_basic"
+        },
+        "provider_info": {
+            "authorization_endpoint":
+                "https://pf.example.com/as/authorization.oauth2",
+            "token_endpoint":
+                "https://pf.example.com/as/token.oauth2",
+            "userinfo_endpoint":
+                "https://pf.example.com/idp/userinfo.openid"
+        },
+        'services': {
+            'Authorization': {},
+            'AccessToken': {},
+            'UserInfo': {}
+        },
+        "keys": {
+            "url": {
+                "https://pf.example.com/": "https://pf.example.com/jwks.json"
+            }
+        }
     }
 
 }

doc/source/rp_handler.rst

@@ -226,6 +226,39 @@ authorization request and accepted by the user.
 
         resp = self.rph.get_user_info(state_key)
 
+:py:meth:`oidcrp.RPHandler.has_active_authentication`
+    After a while when the user returns after having been away for a while
+    you may want to know if you should let her reauthenticate or not.
+    This method will tell you if the last done authentication is still
+    valid or of it has timed out.
+
+    Usage example::
+
+        resp = self.rph.has_active_authentication(state_key)
+
+    response will be True or False depending in the state of the authentication.
+
+:py:meth:`oidcrp.RPHandler.get_valid_access_token`
+    When you are issued a access token they normally comes with a life time.
+    After that time you are expected to use the refresh token to get a new
+    access token. There are 2 ways of finding out if the access token you have
+    passed their life time. You can use this method or you can just try using
+    the access token and see what happens.
+
+    Now, if you use this method and it tells you you have an access token
+    that should still be usable. That is no guarantee that that is the case.
+    things may have happened on the OPs side that makes the access token
+    invalid. So if this method only returns a hint as to the usability of the
+    access token.
+
+    Usage example::
+
+        resp = self.rph.get_valid_access_token(state_key)
+
+    Response will be a tuple containing with the access token and the
+    expiration time (in epoch) if there is a valid access token otherwise an
+    exception will be raised.
+
 ----------------
 RP configuration
 ----------------
@@ -263,6 +296,17 @@ redirect_uris
 behavior
     Information about how the RP should behave towards the OP/AS
 
+keys
+    If the OP doesn't support dynamic provider discovery it may still want to
+    have a way of distributing keys that allows it to rotate them at anytime.
+    To accomplish this some providers have choosen to publish a URL to where
+    you can find their OPs key material in the form of a JWKS.
+
+    Usage example::
+
+        'keys': {'url': {<issuer_id> : <jwks_url>}}
+
+
 If the provider info discovery is done dynamically you need this
 
 client_prefs

src/oidcrp/__init__.py

@@ -754,8 +754,8 @@ def get_valid_access_token(self, state):
         Find me a valid access token
 
         :param state:
-        :return: An access token if a valid one exists otherwise raise
-            exception.
+        :return: An access token if a valid one exists and when it
+            expires. Otherwise raise exception.
         """
 
         exp = 0
@@ -779,12 +779,12 @@ def get_valid_access_token(self, state):
                     try:
                         _exp = response['__expires_at']
                     except KeyError: # No expiry date, lives for ever
-                        indefinite.append(access_token)
+                        indefinite.append((access_token, 0))
                     else:
                         if _exp > now: # expires sometime in the future
                             if _exp > exp:
                                 exp = _exp
-                                token = access_token
+                                token = (access_token, _exp)
 
         if indefinite:
             return indefinite[0]

tests/test_20_rp_handler.py

@@ -549,4 +549,6 @@ def test_has_active_authentication(self):
         assert self.rph.has_active_authentication(self.state)
 
     def test_get_valid_access_token(self):
-        assert self.rph.get_valid_access_token(self.state)
+        (token, expires_at) = self.rph.get_valid_access_token(self.state)
+        assert token == 'accessTok'
+        assert expires_at > 0