"Fossies" - the Fresh Open Source Software Archive

Member "keystone-17.0.0/doc/source/admin/federation/shibboleth.inc" (13 May 2020, 8730 Bytes) of package /linux/misc/openstack/keystone-17.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) fasm source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "shibboleth.inc" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 16.0.1_vs_17.0.0.

    1 .. -*- rst -*-
    2 
    3 ..
    4       Licensed under the Apache License, Version 2.0 (the "License"); you may
    5       not use this file except in compliance with the License. You may obtain
    6       a copy of the License at
    7 
    8       http://www.apache.org/licenses/LICENSE-2.0
    9 
   10       Unless required by applicable law or agreed to in writing, software
   11       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   12       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   13       License for the specific language governing permissions and limitations
   14       under the License.
   15 
   16 .. _shibboleth:
   17 
   18 ---------------------
   19 Setting up Shibboleth
   20 ---------------------
   21 
   22 See :ref:`keystone-as-sp` before proceeding with these Shibboleth-specific
   23 instructions.
   24 
   25 .. note::
   26 
   27    The examples below are for Ubuntu 16.04, for which only version 2 of the
   28    Shibboleth Service Provider is available. Version 3 is available for other
   29    distributions and the configuration should be identical to version 2.
   30 
   31 Configuring Apache HTTPD for mod_shib
   32 -------------------------------------
   33 
   34 .. note::
   35 
   36    You are advised to carefully examine the `mod_shib Apache configuration
   37    documentation`_.
   38 
   39 .. _mod_shib Apache configuration documentation: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig
   40 
   41 Configure keystone under Apache, following the steps in the install guide for
   42 `SUSE`_, `RedHat`_ or `Ubuntu`_.
   43 
   44 .. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server
   45 .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
   46 .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
   47 
   48 Install the Module
   49 ~~~~~~~~~~~~~~~~~~
   50 
   51 Install the Apache module package. For example, on Ubuntu:
   52 
   53 .. code-block:: console
   54 
   55    # apt-get install libapache2-mod-shib2
   56 
   57 The package and module name will differ between distributions.
   58 
   59 Configure Protected Endpoints
   60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   61 
   62 In the Apache configuration for the keystone VirtualHost, set an additional
   63 ``<Location>`` which is not part of keystone's API:
   64 
   65 .. code-block:: apache
   66 
   67    <Location /Shibboleth.sso>
   68        SetHandler shib
   69    </Location>
   70 
   71 If you are using ``mod_proxy``, for example to proxy requests to the
   72 ``/identity`` path to keystone's UWSGI service, you must exempt this Shibboleth
   73 endpoint from it:
   74 
   75 .. code-block:: apache
   76 
   77    Proxypass Shibboleth.sso !
   78 
   79 Configure each protected path to use the ``shibboleth`` AuthType:
   80 
   81 .. code-block:: apache
   82 
   83    <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
   84        Require valid-user
   85        AuthType shibboleth
   86        ShibRequestSetting requireSession 1
   87        ShibExportAssertion off
   88        <IfVersion < 2.4>
   89            ShibRequireSession On
   90            ShibRequireAll On
   91        </IfVersion>
   92    </Location>
   93 
   94 Do the same for the WebSSO auth paths if using horizon as a single sign-on
   95 frontend:
   96 
   97 .. code-block:: apache
   98 
   99    <Location /v3/auth/OS-FEDERATION/websso/saml2>
  100        Require valid-user
  101        AuthType shibboleth
  102        ShibRequestSetting requireSession 1
  103        ShibExportAssertion off
  104        <IfVersion < 2.4>
  105            ShibRequireSession On
  106            ShibRequireAll On
  107        </IfVersion>
  108    </Location>
  109    <Location /v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso>
  110        Require valid-user
  111        AuthType shibboleth
  112        ShibRequestSetting requireSession 1
  113        ShibExportAssertion off
  114        <IfVersion < 2.4>
  115            ShibRequireSession On
  116            ShibRequireAll On
  117        </IfVersion>
  118    </Location>
  119 
  120 Remember to reload Apache after altering the VirtualHost:
  121 
  122 .. code-block:: console
  123 
  124    # systemctl reload apache2
  125 
  126 Configuring mod_shib
  127 --------------------
  128 
  129 .. note::
  130 
  131    You are advised to examine `Shibboleth Service Provider Configuration
  132    documentation
  133    <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
  134 
  135 Generate a keypair
  136 ~~~~~~~~~~~~~~~~~~
  137 
  138 For all SAML Service Providers, a PKI key pair must be generated and exchanged
  139 with the Identity Provider. The ``mod_shib`` package on the Ubuntu distribution
  140 provides a utility to generate the key pair:
  141 
  142 .. code-block:: console
  143 
  144    # shib-keygen -y <number of years>
  145 
  146 which will generate a key pair under ``/etc/shibboleth``. In other cases, the
  147 package might generate the key pair automatically upon installation.
  148 
  149 Configure metadata
  150 ~~~~~~~~~~~~~~~~~~
  151 
  152 ``mod_shib`` also has its own configuration file at
  153 ``/etc/shibboleth/shibboleth2.xml`` that must be altered, as well
  154 as its own daemon. First, give the Service Provider an entity ID. This is a URN
  155 that you choose that must be globally unique to the Identity Provider:
  156 
  157 .. code-block:: xml
  158 
  159    <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
  160        REMOTE_USER="eppn persistent-id targeted-id">
  161 
  162 Depending on your Identity Provider, you may also want to change the REMOTE_USER
  163 setting, more on that in a moment.
  164 
  165 Set the entity ID of the Identity Provider (this is the same as the value you
  166 provided for ``--remote-id`` in `Identity Provider`):
  167 
  168 .. code-block:: xml
  169 
  170    <SSO entityID="https://samltest.id/saml/idp">
  171 
  172 Additionally, if you want to enable ECP (required for Keystone-to-Keystone),
  173 the SSO tag for this entity must also have the ECP flag set:
  174 
  175 
  176 .. code-block:: xml
  177 
  178    <SSO entityID="https://samltest.id/saml/idp" ECP="true">
  179 
  180 Tell Shibboleth where to find the metadata of the Identity Provider. You could
  181 either tell it to fetch it from a URI or point it to a local file. For example,
  182 pointing to a local file:
  183 
  184 .. code-block:: xml
  185 
  186    <MetadataProvider type="XML" file="/etc/shibboleth/samltest-metadata.xml" />
  187 
  188 or pointing to a remote location:
  189 
  190 .. code-block:: xml
  191 
  192    <MetadataProvider type="XML" url="https://samltest.id/saml/idp"
  193        backingFile="samltest-metadata.xml" />
  194 
  195 When you are finished configuring ``shibboleth2.xml``, restart the ``shibd``
  196 daemon:
  197 
  198 .. code-block:: console
  199 
  200    # systemctl restart shibd
  201 
  202 Check the ``shibd`` logs in ``/var/log/shibboleth/shibd.log`` and
  203 ``/var/log/shibboleth/shibd_warn.log`` for errors or warnings.
  204 
  205 Configure allowed attributes
  206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  207 
  208 .. note::
  209 
  210    For more information see the `attributes documentation
  211    <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_
  212 
  213 By default, ``mod_shib`` does not pass all attributes received from the Identity
  214 Provider to keystone. If your Identity Provider does not use attributes known to
  215 ``shibd``, you must configure them. For example, `samltest.id` uses a custom UID
  216 attribute.  It is not discoverable in the Identity Provider metadata, but the
  217 attribute name and type is logged in the ``mod_shib`` logs when an
  218 authentication attempt is made. To allow the attribute, add it to
  219 ``/etc/shibboleth/attribute-map.xml``:
  220 
  221 .. code-block:: xml
  222 
  223    <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid" />
  224 
  225 You may also want to use that attribute as a value for the ``REMOTE_USER``
  226 variable, which will make the ``REMOTE_USER`` variable usable as a parameter to
  227 your mapping rules. To do so, add it to ``/etc/shibboleth/shibboleth2.xml``:
  228 
  229 .. code-block:: xml
  230 
  231    <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
  232        REMOTE_USER="uid">
  233 
  234 Similarly, if using keystone as your Identity Provider, several custom
  235 attributes will be needed in ``/etc/shibboleth/attribute-map.xml``:
  236 
  237 .. code-block:: xml
  238 
  239     <Attribute name="openstack_user" id="openstack_user"/>
  240     <Attribute name="openstack_roles" id="openstack_roles"/>
  241     <Attribute name="openstack_project" id="openstack_project"/>
  242     <Attribute name="openstack_user_domain" id="openstack_user_domain"/>
  243     <Attribute name="openstack_project_domain" id="openstack_project_domain"/>
  244     <Attribute name="openstack_groups" id="openstack_groups"/>
  245 
  246 And update the ``REMOTE_USER`` variable in ``/etc/shibboleth/shibboleth2.xml``
  247 if desired:
  248 
  249 .. code-block:: xml
  250 
  251    <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
  252        REMOTE_USER="openstack_user">
  253 
  254 Restart the ``shibd`` daemon after making these changes:
  255 
  256 .. code-block:: console
  257 
  258    # systemctl restart shibd
  259 
  260 Exchange Metadata
  261 ~~~~~~~~~~~~~~~~~
  262 
  263 Once configured, the Service Provider metadata is available to download:
  264 
  265 .. code-block:: console
  266 
  267    # wget https://sp.keystone.example.org/Shibboleth.sso/Metadata
  268 
  269 Upload your Service Provider's metadata to your Identity Provider. This step
  270 depends on your Identity Provider choice and is not covered here. If keystone
  271 is your Identity Provider you do not need to upload this file.
  272 
  273 Continue configuring keystone
  274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  275 
  276 :ref:`Continue configuring keystone <federation_configuring_keystone>`