.. index:: Configuration; Single Sign On .. index:: Single Sign On .. _sso: Single Sign On ============================ Besides signing up via email/password credentials (optionally restricted by the ``setup_registration_token``, see :ref:`config-general`), users can also sign in via :term:`SSO`. This is :ref:`configured ` in ``global.sso``. Each entry in that dict is the ``name`` of an SSO provider as its key. When choosing a name, it's important to realize that this "name" will also be used in the callback or return URLs! So, this should be a short lower-case alphanumeric identifier, suitable for a URL, like ``foobar`` below. Behind the scenes, all these entries will be set/updated in the database's ``passport_settings`` table by a :ref:`Hub `. After updating the deployment, appropriate hubs will restart automatically. Any other existing rows in that table are not modified, which means if you rename a strategy, you have to delete the row manually. The **"conf" aspect** is basically a set of parameters that are fed into the :term:`Passport JS` strategy, selected by the "type" field. The most important detail is that the URLs have to match. I.e. for example if your strategy is called ``foobar`` then the callbackUrl must be ``https://$DNS/auth/foobar/return``. Obviously, this is also one of the settings that need to be done at your :term:`IdP`. One other important detail is ``login_info``. It maps attributes returned from the "profile" object into cocalc's world. So, e.g. if your :term:`IdP` profile has a field ``firstName`` for the first name of the user, then there must be ``{first_name: 'firstName'}``, i.e. to pick ``firstName`` from the profile object and store it into cocalc's ``first_name``. similarly, ``{emails: "emailAddress"}`` and so on. The string on the right hand side is actually fed into `dot-object `_, which allows you to also reach into nested objects and array. Note: (since version ``3.7.6``) If you end up having to process attributes with dots (e.g. ``foo:bar:1.2.3.4``), you have to change the separator for ``dot-object``. You can do this by setting ``{"_sep" : "->", ...}`` in the ``login_info`` json. With that, accessing works like ``foo->1.2`` when you have to process ``{"foo": {"1.2": ...}}``. The **"info" entries** are for CoCalc's side of this. You should set ``public: false, doNotHide: true``, to show this method on the index page. The ``display``, ``description`` and ``icon`` fields are user-visible elements. Interesting is also ``exclusive_domains`` where you can force users to always authenticate using your :term:`IdP`, when their email address ends with one of the listed domains (or is a sub-domain). That way, you can avoid users setting a password and then still being able to sign in, even if you had cut off their access at the level of your :term:`IdP`. (On top of this, there are also ways to manage user's via an API or cocalc's own Admin interface). As an example, here is how :term:`SAML` Azure AD could look like. Note, that ``type: saml`` and the name of this fictional strategy is ``foobar``, which appears in some parameters. For more information about the SAML Passport JS parameters, check out https://github.com/node-saml/node-saml/blob/master/README.md The up-to-date list of available types is in the `extra-strategies.ts file `_. As of writing this, ``saml``, ``oidc``, and ``oauth2`` / ``oauth2next``, are the ones which are in use and known to work well. You have to check to corresponding :term:`Passport JS` documentation to know what the ``conf`` parameters are. Apart from the example below, please also have a look at this ``sso:`` entry in ``/cocalc/values.yaml`` with more notes and ``/cocalc/cocalc-eu.yaml`` contains another working example. .. literalinclude:: ../_files/sso-samle-azure-ad.yaml :language: yaml :linenos: