Merge pull request #14793 from open-craft/haikuginger/sap-sf-sso-provider

[ENT-285] SAP SuccessFactors SAML provider user metadata

common/djangoapps/third_party_auth/migrations/0007_auto_20170406_0912.py

+# -*- coding: utf-8 -*-
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('third_party_auth', '0006_samlproviderconfig_automatic_refresh_enabled'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='samlproviderconfig',
+            name='identity_provider_type',
+            field=models.CharField(default=b'standard_saml_provider', help_text=b'Some SAML providers require special behavior. For example, SAP SuccessFactors SAML providers require an additional API call to retrieve user metadata not provided in the SAML response. Select the provider type which best matches your use case. If in doubt, choose the Standard SAML Provider type.', max_length=128, verbose_name=b'Identity Provider Type', choices=[(b'standard_saml_provider', b'Standard SAML provider'), (b'sap_success_factors', b'SAP SuccessFactors provider')]),
+        ),
+        migrations.AlterField(
+            model_name='samlproviderconfig',
+            name='other_settings',
+            field=models.TextField(help_text=b'For advanced use cases, enter a JSON object with addtional configuration. The tpa-saml backend supports only {"requiredEntitlements": ["urn:..."]} which can be used to require the presence of a specific eduPersonEntitlement. Custom provider types, as selected in the "Identity Provider Type" field, may make use of the information stored in this field for configuration.', verbose_name=b'Advanced settings', blank=True),
+        ),
+    ]

common/djangoapps/third_party_auth/models.py

@@ -20,6 +20,7 @@ from social.backends.base import BaseAuth
 from social.backends.oauth import OAuthAuth
 from social.backends.saml import SAMLAuth, SAMLIdentityProvider
 from .lti import LTIAuthBackend, LTI_PARAMS_KEY
+from .saml import STANDARD_SAML_PROVIDER_KEY, get_saml_idp_choices, get_saml_idp_class
 from social.exceptions import SocialAuthBaseException
 from social.utils import module_member
 from openedx.core.djangoapps.site_configuration import helpers as configuration_helpers
@@ -350,6 +351,14 @@ class SAMLProviderConfig(ProviderConfig):
     automatic_refresh_enabled = models.BooleanField(
         default=True, verbose_name="Enable automatic metadata refresh",
         help_text="When checked, the SAML provider's metadata will be included in the automatic refresh job, if configured.")
+    identity_provider_type = models.CharField(
+        max_length=128, blank=False, verbose_name="Identity Provider Type", default=STANDARD_SAML_PROVIDER_KEY,
+        choices=get_saml_idp_choices(), help_text=(
+            "Some SAML providers require special behavior. For example, SAP SuccessFactors SAML providers require an "
+            "additional API call to retrieve user metadata not provided in the SAML response. Select the provider type "
+            "which best matches your use case. If in doubt, choose the Standard SAML Provider type."
+        )
+    )
     debug_mode = models.BooleanField(
         default=False, verbose_name="Debug Mode",
         help_text=(
@@ -362,7 +371,9 @@ class SAMLProviderConfig(ProviderConfig):
         help_text=(
             'For advanced use cases, enter a JSON object with addtional configuration. '
             'The tpa-saml backend supports only {"requiredEntitlements": ["urn:..."]} '
-            'which can be used to require the presence of a specific eduPersonEntitlement.'
+            'which can be used to require the presence of a specific eduPersonEntitlement. '
+            'Custom provider types, as selected in the "Identity Provider Type" field, may make '
+            'use of the information stored in this field for configuration.'
         ))
 
     def clean(self):
@@ -423,7 +434,8 @@ class SAMLProviderConfig(ProviderConfig):
             raise AuthNotConfigured(provider_name=self.name)
         conf['x509cert'] = data.public_key
         conf['url'] = data.sso_url
-        return SAMLIdentityProvider(self.idp_slug, **conf)
+        idp_class = get_saml_idp_class(self.identity_provider_type)
+        return idp_class(self.idp_slug, **conf)
 
 
 class SAMLConfiguration(ConfigurationModel):

common/djangoapps/third_party_auth/saml.py

@@ -6,9 +6,12 @@ from django.contrib.sites.models import Site
 from django.http import Http404
 from django.utils.functional import cached_property
 from openedx.core.djangoapps.theming.helpers import get_current_request
-from social.backends.saml import SAMLAuth, OID_EDU_PERSON_ENTITLEMENT
+import requests
+from social.backends.saml import SAMLAuth, SAMLIdentityProvider, OID_EDU_PERSON_ENTITLEMENT
 from social.exceptions import AuthForbidden, AuthMissingParameter
 
+STANDARD_SAML_PROVIDER_KEY = 'standard_saml_provider'
+SAP_SUCCESSFACTORS_SAML_KEY = 'sap_success_factors'
 log = logging.getLogger(__name__)
 
 
@@ -93,3 +96,158 @@ class SAMLAuthBackend(SAMLAuth):  # pylint: disable=abstract-method
     def _config(self):
         from .models import SAMLConfiguration
         return SAMLConfiguration.current(Site.objects.get_current(get_current_request()))
+
+
+class SapSuccessFactorsIdentityProvider(SAMLIdentityProvider):
+    """
+    Customized version of SAMLIdentityProvider that knows how to retrieve user details
+    from the SAPSuccessFactors OData API, rather than parse them directly off the
+    SAML assertion that we get in response to a login attempt.
+    """
+
+    required_variables = (
+        'sapsf_oauth_root_url',
+        'sapsf_private_key',
+        'odata_api_root_url',
+        'odata_company_id',
+        'odata_client_id',
+    )
+
+    @property
+    def sapsf_idp_url(self):
+        return self.conf['sapsf_oauth_root_url'] + 'idp'
+
+    @property
+    def sapsf_token_url(self):
+        return self.conf['sapsf_oauth_root_url'] + 'token'
+
+    @property
+    def sapsf_private_key(self):
+        return self.conf['sapsf_private_key']
+
+    @property
+    def odata_api_root_url(self):
+        return self.conf['odata_api_root_url']
+
+    @property
+    def odata_company_id(self):
+        return self.conf['odata_company_id']
+
+    @property
+    def odata_client_id(self):
+        return self.conf['odata_client_id']
+
+    def missing_variables(self):
+        """
+        Check that we have all the details we need to properly retrieve rich data from the
+        SAP SuccessFactors OData API. If we don't, then we should log a warning indicating
+        the specific variables that are missing.
+        """
+        if not all(var in self.conf for var in self.required_variables):
+            missing = [var for var in self.required_variables if var not in self.conf]
+            log.warning(
+                "To retrieve rich user data for an SAP SuccessFactors identity provider, the following keys in "
+                "'other_settings' are required, but were missing: %s",
+                missing
+            )
+            return missing
+
+    def get_odata_api_client(self, user_id):
+        """
+        Get a Requests session with the headers needed to properly authenticate it with
+        the SAP SuccessFactors OData API.
+        """
+        session = requests.Session()
+        assertion = session.post(
+            self.sapsf_idp_url,
+            data={
+                'client_id': self.odata_client_id,
+                'user_id': user_id,
+                'token_url': self.sapsf_token_url,
+                'private_key': self.sapsf_private_key,
+            },
+            timeout=10,
+        )
+        assertion.raise_for_status()
+        assertion = assertion.text
+        token = session.post(
+            self.sapsf_token_url,
+            data={
+                'client_id': self.odata_client_id,
+                'company_id': self.odata_company_id,
+                'grant_type': 'urn:ietf:params:oauth:grant-type:saml2-bearer',
+                'assertion': assertion,
+            },
+            timeout=10,
+        )
+        token.raise_for_status()
+        token = token.json()['access_token']
+        session.headers.update({'Authorization': 'Bearer {}'.format(token), 'Accept': 'application/json'})
+        return session
+
+    def get_user_details(self, attributes):
+        """
+        Attempt to get rich user details from the SAP SuccessFactors OData API. If we're missing any
+        of the details we need to do that, fail nicely by returning the details we're able to extract
+        from just the SAML response and log a warning.
+        """
+        details = super(SapSuccessFactorsIdentityProvider, self).get_user_details(attributes)
+        if self.missing_variables():
+            # If there aren't enough details to make the request, log a warning and return the details
+            # from the SAML assertion.
+            return details
+        username = details['username']
+        try:
+            client = self.get_odata_api_client(user_id=username)
+            response = client.get(
+                '{root_url}User(userId=\'{user_id}\')?$select=username,firstName,lastName,defaultFullName,email'.format(
+                    root_url=self.odata_api_root_url,
+                    user_id=username
+                ),
+                timeout=10,
+            )
+            response.raise_for_status()
+            response = response.json()
+        except requests.RequestException:
+            # If there was an HTTP level error, log the error and return the details from the SAML assertion.
+            log.warning(
+                'Unable to retrieve user details with username %s from SAPSuccessFactors with company ID %s.',
+                username,
+                self.odata_company_id,
+            )
+            return details
+        return {
+            'username': response['d']['username'],
+            'first_name': response['d']['firstName'],
+            'last_name': response['d']['lastName'],
+            'fullname': response['d']['defaultFullName'],
+            'email': response['d']['email'],
+        }
+
+
+def get_saml_idp_choices():
+    """
+    Get a list of the available SAMLIdentityProvider subclasses that can be used to process
+    SAML requests, for use in the Django administration form.
+    """
+    return (
+        (STANDARD_SAML_PROVIDER_KEY, 'Standard SAML provider'),
+        (SAP_SUCCESSFACTORS_SAML_KEY, 'SAP SuccessFactors provider'),
+    )
+
+
+def get_saml_idp_class(idp_identifier_string):
+    """
+    Given a string ID indicating the type of identity provider in use during a given request, return
+    the SAMLIdentityProvider subclass able to handle requests for that type of identity provider.
+    """
+    choices = {
+        STANDARD_SAML_PROVIDER_KEY: SAMLIdentityProvider,
+        SAP_SUCCESSFACTORS_SAML_KEY: SapSuccessFactorsIdentityProvider,
+    }
+    if idp_identifier_string not in choices:
+        log.error(
+            '%s is not a valid SAMLIdentityProvider subclass; using SAMLIdentityProvider base class.',
+            idp_identifier_string
+        )
+    return choices.get(idp_identifier_string, SAMLIdentityProvider)

common/djangoapps/third_party_auth/tests/testutil.py

@@ -25,6 +25,8 @@ from third_party_auth.models import (
     ProviderApiPermissions,
 )
 
+from third_party_auth.saml import get_saml_idp_class, SAMLIdentityProvider
+
 
 AUTH_FEATURES_KEY = 'ENABLE_THIRD_PARTY_AUTH'
 AUTH_FEATURE_ENABLED = AUTH_FEATURES_KEY in settings.FEATURES
@@ -213,6 +215,16 @@ class SAMLTestCase(TestCase):
         kwargs.setdefault('entity_id', "https://saml.example.none")
         super(SAMLTestCase, self).enable_saml(**kwargs)
 
+    @mock.patch('third_party_auth.saml.log')
+    def test_get_saml_idp_class_with_fake_identifier(self, log_mock):
+        error_mock = log_mock.error
+        idp_class = get_saml_idp_class('fake_idp_class_option')
+        error_mock.assert_called_once_with(
+            '%s is not a valid SAMLIdentityProvider subclass; using SAMLIdentityProvider base class.',
+            'fake_idp_class_option'
+        )
+        self.assertIs(idp_class, SAMLIdentityProvider)
+
 
 @contextmanager
 def simulate_running_pipeline(pipeline_target, backend, email=None, fullname=None, username=None):