Merge pull request #452 from edx/ahodges/sso_open

Ahodges/sso open

en_us/install_operations/source/configuration/index.rst

@@ -19,5 +19,5 @@ configuration options.
    enable_certificates
    enable_badging
    enable_ccx
-   tpa/enable_tpa_edge
-
+   tpa/index
+   

en_us/install_operations/source/configuration/tpa/enable_tpa_edge.rst

@@ -1,4 +1,4 @@
-.. _Enabling Third Party Authentication:
+.. _Enabling Third Party Authentication Edge:
 
 ##################################################
 Enabling Third Party Authentication with edX Edge

en_us/install_operations/source/configuration/tpa/enable_tpa_open.rst

@@ -0,0 +1,23 @@
+.. _Enable the Third Party Authentication Feature:
+
+#################################################
+Enable the Third Party Authentication Feature
+#################################################
+
+By default, third party authentication is not enabled on edX installations. To
+enable this feature, follow these steps.
+
+#. In the ``edx/app/edxapp/lms.env.json`` file, edit the file so that it
+   includes the following line in the features section.
+
+   .. code-block:: json
+
+       "FEATURES" : {
+           ...
+           "ENABLE_COMBINED_LOGIN_REGISTRATION": true,
+           "ENABLE_THIRD_PARTY_AUTH": true
+       }
+
+#. Save the ``edx/app/edxapp/lms.env.json`` file.
+
+

en_us/install_operations/source/configuration/tpa/index.rst

@@ -0,0 +1,28 @@
+.. _Enabling Third Party Authentication:
+
+#######################################
+Enabling Third Party Authentication
+#######################################
+
+To enhance sign in options for your users, you can enable third party
+authentication between institutional authentication systems and your
+implementation of the edX platform. After you enable third party
+authentication, users can register and sign in to your Open edX site with their
+campus or institutional credentials.
+
+.. toctree::
+   :maxdepth: 1
+
+   tpa_providers
+   enable_tpa_open
+   tpa_SAML_SP
+   tpa_SAML_IdP
+   enable_tpa_edge
+
+This section includes information for teams involved in identity management at
+Open edX installations, including DevOps (development operations) and IT. The
+:ref:`Enabling Third Party Authentication Edge` topic describes procedures for
+members of the DevOps and IT teams at an edX partner institution.
+
+.. add xref to section describing complete open edX procedures
+.. Alison 15 Jul 2015

en_us/install_operations/source/configuration/tpa/tpa_SAML_IdP.rst

@@ -0,0 +1,173 @@
+.. _Integrating with a SAML Identity Provider:
+
+##########################################
+Integrating with a SAML Identity Provider
+##########################################
+
+You can integrate your Open edX installation with federated identity solutions
+that use the SAML 2.0 (Security Assertion Markup Language, version 2.0)
+standard. An example is Shibboleth, a single sign on system that is used by
+many educational institutions.
+
+.. contents::
+   :local:
+   :depth: 1
+
+******************
+Exchange Metadata 
+******************
+
+SAML metadata is an XML file that contains the information necessary for secure
+interactions between identity providers and security providers. You send the
+URL of your metadata file, created when you :ref:`configured your installation
+as a SAML service provider<Configuring your Installation as a SAML Service
+Provider>`, to each identity provider that you want to add. Similarly, you
+obtain the metadata URLs from identity providers before you add and enable them
+for your installation.
+
+*******************************************
+Add and Enable a SAML Identity Provider
+*******************************************
+
+To add and enable a SAML 2.0 identity provider, follow these steps.
+
+#. Log in to the Django administration console for your base URL. For example,
+   ``http://{your_URL}/admin``.
+
+#. In the **Third_Party_Auth** section, next to **Provider Configuration
+   (SAML IdPs)** select **Add**.
+
+   .. note:: If you want to change the configuration of an existing provider, 
+    next to **Provider Configuration (SAML IdPs)** select **Change**, and then
+    select **Update** for the provider that you want to configure.
+
+3. Enter the following information for the provider.
+
+ - **Icon class**: Specifies a `Font Awesome`_ image for the button that users
+   will select to access the sign in page for this IdP. The **fa-sign-in** icon
+   is used by default. For university or institutional providers, a suggested
+   alternative is **fa-university**.
+
+ - **Name**: The name of the IdP as you want it to appear on the sign in page.
+
+ - **Secondary**: Select this option to include the IdP in an intermediary list
+   of providers that users access from a **Use my institution/campus
+   credentials** button on the sign in page.
+
+ - **Backend name**: The default, **tpa-saml**, is optimized for use with Open
+   edX and works with most SAML providers. Select a different option only
+   if you have added a custom backend that provides additional functionality.
+
+ - **IdP slug**: A short, unique name to identify this IdP in the URL. The slug
+   becomes part of a URL, so the value that you enter cannot include spaces.
+
+ - **Entity ID**: The URI that identifies the IdP. This ID must match
+   the value specified in the metadata XML file.
+
+ - **Metadata source**: The URL of the XML file that contains this provider's
+   metadata.
+
+4. Specify your selections for any of the other, optional configuration
+   options. For more information about these options, see :ref:`Configuration
+   Options for SAML Providers`.
+
+#. When you are ready to enable the provider, select **Enabled** at the top of
+   the page. Alternatively, save your configuration settings and enable the
+   provider at another time.
+
+#. Select **Save** or one of the other save options at the bottom of the page.
+
+Next, you can :ref:`test an enabled provider<Test an Enabled SAML Provider>`.
+
+.. _Configuration Options for SAML Providers:
+
+*************************************************
+Configuration Options for SAML Identity Providers
+*************************************************
+
+To customize the registration process for IdP, you make selections for these
+optional fields on the Add Provider Configuration (SAML IdP) page.
+
+* **Skip Registration Form**: If you select this option, users are not asked to
+  confirm the user account data supplied for them by the IdP (name, email
+  address, and so on). Select this option only for providers that are known to
+  provide accurate user information.
+
+  By default, users review a registration form with the supplied account
+  details.
+
+* **Skip Email Verification**: If you select this option, users are not
+  required to confirm their email addresses, and their accounts are activated
+  immediately upon registration.
+
+  By default, users receive an email message and must select a link in that
+  message to activate their user accounts.
+
+* **User ID Attribute**: Required. This value is used to associate the user's
+  edX account with the campus account. It is not displayed to users.
+
+  By default, uses ``userid``, ``urn:oid:0.9.2342.19200300.100.1.1``.
+
+* Optional user attributes: You can indicate specific URN values for the
+  following user attributes. 
+
+  By default, the registration form includes all of the following attributes if
+  they are sent by the IdP.
+
+  * **Full Name Attribute**: ``commonName``, ``urn:oid:2.5.4.3``
+  * **First Name Attribute**: ``givenName``, ``urn:oid:2.5.4.42``
+  * **Last Name Attribute**: ``surname``, ``urn:oid:2.5.4.4``
+  * **Username Hint Attribute**: ``userid``, 
+    ``urn:oid:0.9.2342.19200300.100.1.1``
+  * **Email Attribute**: ``mail``, ``urn:oid:0.9.2342.19200300.100.1.3``
+
+  If the identity provider sends a value that you do not want to be included on
+  the the registration form, you can enter a value such as "DISABLED" or
+  "IGNORE" in that field.
+
+.. _Test an Enabled SAML Provider:
+
+*******************************************
+Test an Enabled SAML Provider
+*******************************************
+
+To verify the sign in process for an IdP that you have enabled, follow these
+steps.
+
+#. On the Django administration console, in the **Third_Party_Auth** section,
+   select **Provider Configuration (SAML IdPs)**.
+
+#. Check the icon in the **Metadata ready** column for the IdP. After the
+   provider's metadata is fetched successfully from the URL that you provided
+   as the metadata source, a check mark in a green circle appears and the
+   provider is ready for use immediately.
+
+   You might need to wait 30-60 seconds for the task to complete, and then
+   refresh this page.
+
+   If the check mark does not appear, make sure that celery is configured
+   correctly and is running. You can also manually trigger an update by running
+   the management command ``./manage.py lms saml pull --settings=aws`` on
+   Fullstack or ``./manage.py lms saml pull --settings=devstack`` on Devstack.
+
+3. For additional information about the data fetched from the IdP, on the
+   Django administration console select **SAML Provider Data**, and then select
+   the provider. The page that opens reports data fetched from the metadata
+   source URL and the date and time it was fetched.
+
+#. To verify that users can use the IdP for sign in, go to the sign in page for
+   your LMS. The page should include the institutional sign in button.
+
+   .. image:: ../../Images/tpa_signin.png
+     :alt: Screen shot of an LMS sign in page with a button labeled "Use my
+         institutional/campus credentials" circled at the bottom.
+
+5. Select **Use my institutional/campus credentials**. The list of providers
+   that appears should include the IdP that you enabled.
+
+   .. image:: ../../Images/tpa_inst_list.png
+     :alt: Screen shot of the list of enabled IdPs. Each IdP name is linked to
+         the sign in page for the corresponding authentication system.
+
+
+.. include:: ../../links.rst

en_us/install_operations/source/configuration/tpa/tpa_SAML_SP.rst

@@ -0,0 +1,113 @@
+.. _Configuring your Installation as a SAML Service Provider:
+
+###############################################################
+Configuring your Installation as a SAML Service Provider 
+###############################################################
+
+The first step in configuring your Open edX installation to act as a SAML SP
+(service provider) is to create a credential key pair to ensure secure data
+transfers with identity providers. To complete the configuration procedure, you
+configure your Open edX installation as a SAML service provider which creates
+your metadata XML file.
+
+.. contents::
+   :local:
+   :depth: 1
+
+After you complete this configuration, you can share your metadata file with
+SAML identity providers, and configure them to assert identity and access
+rights for users to your installation. For more information, see
+:ref:`Integrating with a SAML Identity Provider`.
+
+**********************************************
+Generate Public and Private Keys
+**********************************************
+
+To generate the keys for your Open edX installation, follow these steps.
+
+#. On your local computer or on the server, open Terminal or a Command Prompt
+   and run the following command.
+
+   ``openssl req -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.key``
+
+#. Provide information at each prompt. 
+
+Two files, ``saml.crt`` and ``saml.key``, are created in the directory where
+you ran the command.
+
+**************************************************
+Configure your Installation as a Service Provider
+**************************************************
+
+To configure your Open edX installation as a SAML service provider, follow
+these steps.
+
+#. Sign in to the Django administration console for your base URL. For example,
+   ``http://{your_URL}/admin``.
+
+#. In the **Third_Party_Auth** section, next to **SAML Configuration** select
+   **Add**.
+
+#. Select **Enabled**.
+
+#. Enter the following information.
+
+  - **Private key**: Use a text editor to open the ``saml.key`` file, and then
+    copy the RSA private key into this field.
+
+  - **Public key**: Use a text editor to open the ``saml.crt`` file, and then
+    copy the certificate into this field.
+
+  - **Entity ID**: Enter a URI for the server. To ensure that this value
+    uniquely identifies your site, the naming convention that edX recommends is
+    to include the server's domain name. For example,
+    ``http://saml.mydomain.com/``.
+
+  - **Organization Info**: Use the format in the example that follows to
+    specify a language and locale code and identifying information for your
+    installation.
+
+    .. code:: json
+
+     {
+        "en-US": {
+            "url": "http://www.mydomain.com",
+            "displayname": "{Complete Name}",
+            "name": "{Short Name}"
+        }
+     }
+
+  - **Other config str**: Define the security settings for the IdP metadata
+    files. For more information about the security settings, see the `Python SAML Toolkit`_. An example follows.
+
+    .. code:: json
+
+     { 
+        "SECURITY_CONFIG": {
+          "signMetadata": false, 
+          "metadataCacheDuration": ""
+        }
+     }
+
+5. Select **Save** at the bottom of the page. You can direct identity providers
+   to ``{your LMS URL}/auth/saml/metadata.xml`` for your metadata file.
+
+*******************************************************
+Ensure that the SAML Authentication Backend is Loaded
+*******************************************************
+
+By default, SAML is included as an approved data format for identity providers.
+The default configuration of the ``/edx/app/edxapp/lms.env.json`` file does not
+explicitly include the ``THIRD_PARTY_AUTH_BACKENDS`` setting.
+
+If you have customized this file and added the ``THIRD_PARTY_AUTH_BACKENDS``
+setting to it, you might need to verify that the
+``third_party_auth.saml.SAMLAuthBackend`` python-social-auth backend class is
+specified for it. That backend is required before you can add SAML IdPs.
+
+To verify that the SAML authentication backend is loaded on a devstack or
+fullstack installation, review the ``/edx/app/edxapp/lms.env.json`` file.
+
+
+.. include:: ../../links.rst
+

en_us/install_operations/source/configuration/tpa/tpa_providers.rst

@@ -0,0 +1,39 @@
+.. _Supported Identity Providers:
+
+#######################################
+Supported Identity Providers
+#######################################
+
+In an exchange of authentication and authorization data, an identity provider
+securely asserts the identity and access rights of a set of users. Your
+implementation of the Open edX platform is the service provider that allows
+the users access on the basis of credentials sent by an identity provider.
+
+For example, your Open edX installation hosts the courses of three different
+institutions. When you configure the open edX installation to be a service
+provider, and configure each of the three institutions to be identity
+providers, you permit learners who have valid user credentials at any of
+those institutions to access the Open edX site. 
+
+.. You can enable third party authentication between your Open edX system and identity providers that use the SAML 2.0 (Security Assertion Markup Language, version 2.0) or OAuth2 standards for authentication. For more information, see :ref:`Integrating with a SAML Identity Provider` or :ref:`Integrating with an OAuth2 Identity Provider`.
+
+.. replace the following para with the above para when ready to add OAuth2 
+.. - Alison 5 Aug 15
+
+You can enable third party authentication between your Open edX system and
+identity providers that use the SAML 2.0 (Security Assertion Markup Language,
+version 2.0). For more information, see :ref:`Integrating with a SAML Identity
+Provider`.
+
+.. Regardless of the standard that the identity provider you want to integrate with uses, you begin by :ref:`enabling the third party authentication feature<Enable the Third Party Authentication Feature>` for your installation.
+
+.. replace the following para with the above para when ready to add OAuth2 
+.. - Alison 5 Aug 15
+
+At an Open edX installation, you begin by :ref:`enabling the third party
+authentication feature<Enable the Third Party Authentication Feature>` for your
+installation.
+
+At an institution that has a partner membership with edX, you can :ref:`enable
+third party authentication<Enabling Third Party Authentication Edge>` between
+your institutional authentication systems and the edX Edge site.