Configuring SSO

Owned by Rihards Pacevics
Last updated: Apr 02, 2024 by Thomas Frickh
4 min read

Single Sign-On (SSO) is a crucial component of modern authentication systems, enabling users to access multiple applications with a single set of credentials. This guide will help you to configure SSO for your instance.

 Prerequisites

Before you begin, make sure you have the following:

  1. Access to the tenants SSO settings.

  2. An identity provider (IdP) that supports SAML 2.0, such as Okta, OneLogin, or Azure Active Directory.

  3. IdP Federation metadata of Avallone.

Before users can login into their instance they will need to have users created before in the instance.

 Step-by-Step Guide

1. Configure Identity Provider (IdP)

  1. Download Avallone Federation metadata from the tenants SSO settings

    It will open a XML format file with Avallone federation metadata. Copy the contents into a .xml extension file and save it on your computer.

    e.g example metadata

    <?xml version="1.0" encoding="UTF-8" standalone="no"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://saml.example.com/entityid" validUntil="2033-08-17T07:56:47.812Z"> <md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate>MIIC4jCCAcoCCQC33wnybT5QZDANBgkqhkiG9w0BAQsFADAyMQswCQYDVQQGEwJV SzEPMA0GA1UECgwGQm94eUhRMRIwEAYDVQQDDAlNb2NrIFNBTUwwIBcNMjIwMjI4 MjE0NjM4WhgPMzAyMTA3MDEyMTQ2MzhaMDIxCzAJBgNVBAYTAlVLMQ8wDQYDVQQK DAZCb3h5SFExEjAQBgNVBAMMCU1vY2sgU0FNTDCCASIwDQYJKoZIhvcNAQEBBQAD ggEPADCCAQoCggEBALGfYettMsct1T6tVUwTudNJH5Pnb9GGnkXi9Zw/e6x45DD0 RuRONbFlJ2T4RjAE/uG+AjXxXQ8o2SZfb9+GgmCHuTJFNgHoZ1nFVXCmb/Hg8Hpd 4vOAGXndixaReOiq3EH5XvpMjMkJ3+8+9VYMzMZOjkgQtAqO36eAFFfNKX7dTj3V pwLkvz6/KFCq8OAwY+AUi4eZm5J57D31GzjHwfjH9WTeX0MyndmnNB1qV75qQR3b 2/W5sGHRv+9AarggJkF+ptUkXoLtVA51wcfYm6hILptpde5FQC8RWY1YrswBWAEZ NfyrR4JeSweElNHg4NVOs4TwGjOPwWGqzTfgTlECAwEAATANBgkqhkiG9w0BAQsF AAOCAQEAAYRlYflSXAWoZpFfwNiCQVE5d9zZ0DPzNdWhAybXcTyMf0z5mDf6FWBW 5Gyoi9u3EMEDnzLcJNkwJAAc39Apa4I2/tml+Jy29dk8bTyX6m93ngmCgdLh5Za4 khuU3AM3L63g7VexCuO7kwkjh/+LqdcIXsVGO6XDfu2QOs1Xpe9zIzLpwm/RNYeX UjbSj5ce/jekpAw7qyVVL4xOyh8AtUW1ek3wIw1MJvEgEPt0d16oshWJpoS1OT8L r/22SvYEo3EmSGdTVGgk3x3s+A0qWAqTcyjr7Q4s/GKYRFfomGwz0TZ4Iw1ZN99M m0eo2USlSRTVl7QHRTuiuSThHpLKQQ== </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://mocksaml.com/api/saml/sso"/> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://mocksaml.com/api/saml/sso"/> </md:IDPSSODescriptor> </md:EntityDescriptor>

     

This part needs to be done by tenants IT

  1. Log in to your chosen identity provider (IdP) console.

  2. Create a new application or service provider (SP) configuration.

  3. Provide the necessary information about the app, including its name and federation metadata.

  4. Here are examples with different IdP provider configurations from the SSO library Avallone is using https://boxyhq.com/docs/jackson/sso-providers

2. Obtain Metadata from IdP

  1. In the IdP console, locate the SAML 2.0 metadata for the app's configuration.

  2. This metadata usually comes in XML format and includes information about the IdP, endpoints, certificates, and more.

  3. Copy the SAML 2.0 metadata XML to your clipboard or save it as a file.

3. Configure tenants SSO settings in Avallone

  1. Log in to the app's settings interface.

  2. Navigate to the SSO settings section.

  3. Create a new connection → Fill out the information

    1. Title, Description. The title will be shown on the login page.

    2. Select the desired identifier format (if not sure what to select, pick unspecified)

    3. For Metadata URL -> get the url from IdP if provided.

    4. Alternatively you can add the Raw Metadata in a string format. This basically means adding previously saved XML data from the IdP metadata information directly in the field.

  4. If you want to force users to re-authenticate every time they are accessing the app, check the ForceAuth checkbox.

  5. Click save & close button.

 

  1. If you want to turn off the username and password login and have only SSO login enabled. After creating the connection in the SSO settings page click on Enable SSO login only.

5. Test SSO Configuration

  1. Open newly created SSO connection from the connection list.

 

  1. In order to view the SSO login button copy the SSO login url and save it in your browser.

 

  1. Log out from the tenant and open the link with previously saved SSO login url.

  2. Click on the newly created SSO connection, you should be redirected to you IdP login page.

  3. Log in using your IdP credentials.

  4. If configured correctly, you should be redirected back to the app and logged in automatically.

6. Troubleshooting and Fine-Tuning

  1. If the SSO process fails, review the error messages provided by both the Avallone app and the IdP.

  2. Double-check the metadata XML for accuracy.

7. Roll Out to Users

  1. Once you are confident in your SSO configuration, consider rolling it out to a small group of users for testing.

  2. Monitor the rollout for any issues or user feedback.

  3. Gradually expand the rollout to all users after successful testing.