Features Cookbook
=================

Requesting Claims
-----------------

Specific claims can be requested using the Authorization request parameter

::

    from oic.oic.message import ClaimsRequest, Claims

    claims_request = ClaimsRequest(
        id_token=Claims(
          email={"essential": None},
          phone_number=None
        ),
        userinfo=Claims(
          given_name={"essential": True},
          family_name={"essential": True}, nickname=None
        )
    )

    request_args = {
        "redirect_uri": "https://example.com/rp/authz_cb",
        "scope": "openid",
        "response_type": "code",
        "claims": claims_request
    }

    # client is oic.oic.Client
    client.construct_AuthorizationRequest(request_args=request_args)

Client Assertions
-----------------

Client assertions can be used for authentication at the IdP token endpoint in
the OIDC authorization code flow, rather than a client secret. As a challenging
example, we'll use authenticating with a Microsoft Azure AD IdP, as this
additionally involves creating a custom client assertion.

Support for client assertions is provided in the ``do_access_token_request``
method of the ``oic.oic.Client`` class, using keyword arguments to the method:

::

            kwargs = dict(algorithm="RS256", authn_endpoint='token',
                          authn_method="private_key_jwt")

The ``authn_method`` parameter initiates authentication with a client assertion.
The ``algorithm`` and ``authn_endpoint`` parameters are needed by the
``oic.utils.authn.client.PrivateKeyJWT`` class to properly construct the
assertion. Also required is a signing key in the client's keyjar. A way to
accomplish this is illustrated by the ``TestPrivateKeyJWT`` test in
*tests/test_client.py*

::

    _key = rsa_load(os.path.join(BASE_PATH, "data/keys/rsa.key"))
    kc_rsa = KeyBundle([{"key": _key, "kty": "RSA", "use": "ver"},
                        {"key": _key, "kty": "RSA", "use": "sig"}])
    client.keyjar[""] = kc_rsa

The test also illustrates how you can directly generate the assertion and
inspect it.  The JWT payload contents can be understood by examining the
``assertion_jwt`` function in ``oic.utils.authn.client``.

So that's basically all you need to know if your IdP can use pyoidc's client
assertions.  If you're using out-of-band client registration, you would not
include a ``client_secret`` when constructing the ``RegistrationResponse``,
as shown in pyoidc's relying party documentation.

To use client assertions with Microsoft AzureAD, Microsoft provides this
`guidance
<https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-certificate-credentials>`_.
The differences from the client assertion pyoidc generates are:

* the ``typ`` and ``x5t`` header claims must be included.
* the payload claim ``iat`` is instead ``nbf``

pyoidc nicely provides a ``client_assertion`` keyword argument to
``do_access_token_request``. This argument's value is substituted for the
client assertion pyoidc would otherwise generate. Note that the other keyword
arguments identified above are still required:

::

            kwargs = dict(algorithm="RS256", authn_endpoint='token',
                          authn_method="private_key_jwt",
                          client_assertion=custom_assertion)


Generating a custom client assertion for Microsoft is illustrated by the
function below.

::

    import json
    from jwkest.jws import JWSig, SIGNER_ALGS
    from jwkest.jwt import b64encode_item
    from oic import rndstr
    from oic.utils.time_util import utc_time_sans_frac


    def make_assertion(client_id, token_endpoint, fingerprint, key, lifetime=60):
        """Creates a JWT for IdP token endpoint auth per Microsoft specs"""
        _alg = "RS256"
        headers = {'alg': _alg, 'typ': "JWT", 'x5t': fingerprint}
        _now = utc_time_sans_frac()
        payload = dict(
            iss=client_id,
            sub=client_id,
            aud=token_endpoint,
            jti=rndstr(32),
            nbf=_now,
            exp=_now + lifetime
        )
        jwt = JWSig(**headers)
        _signer = SIGNER_ALGS[_alg]
        _input = jwt.pack(parts=[json.dumps(payload)])
        sig = _signer.sign(_input.encode("utf-8"),
                           key.get_key(alg=_alg, private=True))
        return ".".join([_input, b64encode_item(sig).decode("utf-8")])


The ``client_id`` and ``token_endpoint`` arguments to this function should be
straightforward. ``key`` is a ``jwkest.jwk.RSAKey``. To create one from a
certificate private key file at ``path``:

::

    from jwkest.jwk import rsa_load, RSAKey
    signing_key = RSAKey(key=rsa_load(path), kty="RSA", use='sig')


``fingerprint`` is a Base64 encoded SHA-1 fingerprint of the X.509 certificate
corresponding to the private key. Microsoft Azure AD displays this fingerprint
as a hexadecimal string when the certificate is registered during IdP
configuration. You can easily convert this string by:

::

    from base64 import b64encode
    from binascii import unhexlify
    fingerprint = b64encode(unhexlify(hex_string))


If you don't have the hexadecimal fingerprint, but you have the X.509
certificate file, you can generate the fingerprint, as shown below using the
``cryptography`` package:

::

    from base64 import b64encode
    from binascii import hexlify
    from cryptography import x509
    from cryptography.hazmat.backends import default_backend
    from cryptography.hazmat.primitives import hashes
    with open("cert.pem", "rb") as f:
        cert = x509.load_pem_x509_certificate(f.read(), default_backend())
    fingerprint = cert.fingerprint(hashes.SHA1())
    hexadecimal_fingerprint = hexlify(fingerprint).upper()
    base64_fingerprint = b64encode(fingerprint)


Putting it together

::

    def make_token_request(client, state, code, redirect_uri, scopes, assertion):
        """Retrieves tokens by redeeming an authorization code"""
        request_args = dict(
            client_id=client.client_id,
            code=code,
            redirect_uri=redirect_uri
        )
        kwargs = dict(
            algorithm="RS256",
            authn_endpoint='token',
            authn_method="private_key_jwt",
            client_assertion=assertion,
            request_args=request_args,
            scope=scopes,
            state=state
        )
        return client.do_access_token_request(**kwargs)