(As an alternative to IIS, SSO is also possible with for example Apache and

    mod_sspi.)

    Mercurial and Git do however by default not support SSO on the client side

    and will still require some other kind of authentication.

    (An extension like hgssoauthentication_ might solve that.)

.. note::

    For the best security, it is strongly recommended to only host the site over

    a secure connection, e.g. using TLS.

Prerequisites

-------------

Apart from the normal requirements for Kallithea, it is also necessary to get an

ISAPI-WSGI bridge module, e.g. isapi-wsgi.

Installation

------------

The following assumes that your Kallithea is at ``c:\inetpub\kallithea``, and

will be served from the root of its own website. The changes to serve it in its

own virtual folder will be noted where appropriate.

Application pool

^^^^^^^^^^^^^^^^

Make sure that there is a unique application pool for the Kallithea application

with an identity that has read access to the Kallithea distribution.

The application pool does not need to be able to run any managed code. If you

are using a 32-bit Python installation, then you must enable 32-bit program in

the advanced settings for the application pool; otherwise Python will not be able

to run on the website and neither will Kallithea.

.. note::

    The application pool can be the same as an existing application pool,

    as long as the Kallithea requirements are met by the existing pool.

ISAPI handler

^^^^^^^^^^^^^

The ISAPI handler can be generated using::

This will generate a ``dispatch.py`` file in the current directory that contains

the necessary components to finalize an installation into IIS. Once this file

has been generated, it is necessary to run the following command due to the way

that ISAPI-WSGI is made::

    python2 dispatch.py install

This accomplishes two things: generating an ISAPI compliant DLL file,

``_dispatch.dll``, and installing a script map handler into IIS for the

``--virtualdir`` specified above pointing to ``_dispatch.dll``.

The ISAPI handler is registered to all file extensions, so it will automatically

be the one handling all requests to the specified virtual directory. When the website starts

the ISAPI handler, it will start a thread pool managed wrapper around the

middleware WSGI handler that Kallithea runs within and each HTTP request to the

site will be processed through this logic henceforth.

Authentication with Kallithea using IIS authentication modules

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The recommended way to handle authentication with Kallithea using IIS is to let

IIS handle all the authentication and just pass it to Kallithea.

.. note::

    As an alternative without SSO, you can also use LDAP authentication with

    Active Directory, see :ref:`ldap-setup`.

To move responsibility into IIS from Kallithea, we need to configure Kallithea

to let external systems handle authentication and then let Kallithea create the

user automatically. To do this, access the administration's authentication page

and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is

added, enable it with the ``REMOTE_USER`` header and check *Clean username*.

Finally, save the changes on this page.

Switch to the administration's permissions page and disable anonymous access,

otherwise Kallithea will not attempt to use the authenticated user name. By

default, Kallithea will populate the list of users lazily as they log in. Either

disable external auth account activation and ensure that you pre-populate the

user database with an external tool, or set it to *Automatic activation of

external account*. Finally, save the changes.

The last necessary step is to enable the relevant authentication in IIS, e.g.

Windows authentication.

Troubleshooting

# -*- coding: utf-8 -*-

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

# 'cli' is the main entry point for 'kallithea-cli', specified in setup.py as entry_points console_scripts

from kallithea.bin.kallithea_cli_base import cli

# import commands (they will add themselves to the 'cli' object)

import kallithea.bin.kallithea_cli_config

import kallithea.bin.kallithea_cli_ishell

import kallithea.bin.kallithea_cli_repo

# -*- coding: utf-8 -*-

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

import os

dispath_py_template = '''\

import sys

if hasattr(sys, "isapidllhandle"):

    import win32traceutil

import isapi_wsgi

import os

def __ExtensionFactory__():

    from paste.deploy import loadapp

    from paste.script.util.logging_config import fileConfig

    fileConfig('%(inifile)s')

    application = loadapp('config:%(inifile)s')

    def app(environ, start_response):

        user = environ.get('REMOTE_USER', None)

        if user is not None:

            os.environ['REMOTE_USER'] = user

        return application(environ, start_response)

    return isapi_wsgi.ISAPIThreadPoolHandler(app)

if __name__=='__main__':

    from isapi.install import *

    params = ISAPIParameters()

    sm = [ScriptMapParams(Extension="*", Flags=0)]

    vd = VirtualDirParameters(Name="%(virtualdir)s",

                              Description = "Kallithea",

                              ScriptMaps = sm,

                              ScriptMapUpdate = "replace")

    params.VirtualDirs = [vd]

    HandleCommandLine(params)

'''

        try:

            import isapi_wsgi

        except ImportError:

        dispatchfile = os.path.join(os.getcwd(), 'dispatch.py')

        with open(dispatchfile, 'w') as f:

            f.write(dispath_py_template % {

                })

            'to generate the _dispatch.dll file and install it into the '

import setuptools

# monkey patch setuptools to use distutils owner/group functionality

from setuptools.command import sdist

sdist_org = sdist.sdist

class sdist_new(sdist_org):

    def initialize_options(self):

        sdist_org.initialize_options(self)

        self.owner = self.group = 'root'

sdist.sdist = sdist_new

packages = setuptools.find_packages(exclude=['ez_setup'])

setuptools.setup(

    name='Kallithea',

    version=__version__,

    description=description,

    long_description=long_description,

    keywords=keywords,

    license=__license__,

    author=__author__,

    author_email='kallithea@sfconservancy.org',

    dependency_links=dependency_links,

    url=__url__,

    install_requires=requirements,

    classifiers=classifiers,

    data_files=data_files,

    packages=packages,

    include_package_data=True,

    message_extractors={'kallithea': [

            ('**.py', 'python', None),

            ('templates/**.mako', 'mako', {'input_encoding': 'utf-8'}),

            ('templates/**.html', 'mako', {'input_encoding': 'utf-8'}),

            ('public/**', 'ignore', None)]},

    zip_safe=False,

    entry_points="""

    [console_scripts]

    kallithea-api =    kallithea.bin.kallithea_api:main

    kallithea-gist =   kallithea.bin.kallithea_gist:main

    kallithea-config = kallithea.bin.kallithea_config:main

    kallithea-cli =    kallithea.bin.kallithea_cli:cli

    [paste.app_factory]

    main = kallithea.config.middleware:make_app

    [gearbox.commands]

    celeryd=kallithea.lib.paster_commands.celeryd:Command

    make-index=kallithea.lib.paster_commands.make_index:Command

    make-rcext=kallithea.lib.paster_commands.make_rcextensions:Command

    setup-db=kallithea.lib.paster_commands.setup_db:Command

    upgrade-db=kallithea.lib.dbmigrate:UpgradeDb

    """,

)