Skip to content

Single Sign-On

A CNXION powered platform may opt to enable SAML Single Sign-On functionality which allows it to run as Service Provider role with a seamless authentication flow and integrate with foreign Identity Providers (also known as an Authentication Server).

Vocabulary

  • Identity provider - system entity that issues authentication assertions in conjunction with a single sign-on (SSO) profile

  • Service provider - system entity that receives and accepts authentication assertions in conjunction with a single sign-on (SSO) profile

  • CNXION powered platform - tenant/website that is run on CNXION

Overview

This page is for Identity Providers wanting to integrate with CNXION powered platform. CNXION powered platform acts as a Service Provider.

Integration allows to authorise user in a CNXION powered platform without needing to create account. What is used for authentication is an already existing account on a different website. This creates a nice user experience, reduces security risks through credentials saved in multiple databases, and eases support and sync of accounts across platforms.

Integration requires exchange of public keys, endpoint information and negotiation of data provided by Identity Provider to Service Provider during end user authorisation.

SSO SAML for the CNXION powered platform is based on SAML authentication backend of Python Social Auth library. You can refer to aforementioned libraries documentation for better understanding of the exact processes used in a CNXION powered platform.

Use cases

There are two scenarios of user authorisation:

  • From Authentication Server (Identity Provider) side
  • From CNXION powered platform (Service Provider) itself

When authorisation is initiated from Authentication Server side:

  • User first authorises at Authentication Server.
  • Authentication Server authorizes user in a CNXION powered platform and in the end redirects user to the CNXION powered platform

When authorisation is initiated from CNXION powered platform (for example by clicking a "Log In" link) side:

  • User is redirected to an endpoint on the Authentication Server side for authorisation.

High-level integration instructions

  • Implement SAML SSO capable Identity Provider

  • Generate key pair

  • Verify capability of your Identity Provider using samltest service

    • Register Identity Provider metadata in samltest service
    • Run through Identity Provider testing flow at samltest service

  • Gather following details of your Identity Provider (for reference please see https://samltest.id/download/#SAMLtests_IdP)

    • endpoints
    • entityID - endpoint at which Identity Provider provides SAML metadata; it is used by Service Provider to represent Identity Provider internally.
    • Redirect SSO Location - endpoint at which Identity Provider will handle its authorisation logic that Service Provider will use to redirect users that want to login to Service Provider's website.
    • information about attributes that are sent (or can be sent) to Service Provider during SAML authentication flow (for example please see https://samltest.id/download/#Attributes_Sent).
    • make sure to send uid (urn:oid:0.9.2342.19200300.100.1.1) attribute with SAML response. Otherwise we won't be able to uniquely identify users
    • make sure to send profile-type attribute with SAML response to specify which profile user is signing in as. Example: <saml2:Attribute FriendlyName="profile-type" Name="urn:cnxion:dir:attribute-def:profile-type" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml2:AttributeValue>[2]</saml2:AttributeValue> </saml2:Attribute>

  • Provide endpoints, public key, entityID, Redirect SSO Location and information about attributes to Service Provider, so we (CNXION) can configure Service Provider with these settings

  • Use table in Integration endpoints to check the link for obtaining Service Provider configuration. Presumably you want to download <tenant-domain-name>/sso/sp/ and store it in your Identity Provider configuration.

  • Request Service Provider for public key or refer to entity ID of a Service Provider.

  • Test bare authentication flow:

    • Authentication from Service Provider side
    • Authentication from Identity Provider side

  • Contact with Service Provider to perform further integration, which includes:

    • Negotiation of data passed via SAML auth attributes.

  • Debug and fine-tune of the authorisation process

Testing

During integration process you can verify your software is matching SSO SAML protocol with testing it at https://samltest.id and ensure it functions as expected.

Here you can find a screencast showing how authenticating into CNXION powered platform works with samltest.id as an Identity Provider:

Flow is following:

  • as a user access CNXION powered platform
  • as a user you are not logged in
  • you click "log in"
  • you are redirected to samltest.id which is configured as an Identity Provider for testing purposes
  • you log in inside samltest.id using one of the example accounts
  • you are asked to approve/reject sharing user data with CNXION powered platform
  • if you accept, you are redirected back to CNXION powered platform
  • you are automatically logged in and user data is synced

Integration endpoints

CNXION Endpoints involved into authorisation process.

Endpoint Reference Name Description
<tenant-domain-name>/sso/sp/ entityID Endpoint that provides Service Provider SAML metadata containing all information required for authorisation process
<tenant-domain-name>/sso/login/saml/ SP-Initiated login Initiates the SSO process from Service Provider side by redirecting to Identity Provider
<tenant-domain-name>/sso/complete/saml/ AssertionConsumerService URL Completes SSO process, validates payload, does user creation, preparation and session initialisation

Encryption keys

Both Identity Provider and Service Provider are using pair of keys - private and public.

  • Private Key is kept hidden and used to sign payload of SAML document.

  • Public Key is shared with counterpart to verify authenticity of received request.