Single sign-on & User provisioning
When do you need this
When you need enhanced security mechanisms typically available with an SSO provider (e.g. Two factor authentication)
When end users need to be able to login with their company account and password, which reduces the need to remember or manage different passwords.
When you have a lot of users and managing their passwords and accounts is becoming time intensive. When there is a need to manage these accounts in a centralised way.
Terminology explanation
Single Sign-on
What is this? Single Sign-On gives your users the ability to sign in to different applications using the same unique set of username and password. Users sign in once using a Microsoft or Office login and by this they are automatically logged in into other apps.
Use case? Sign-on in Peripass with company account
User Provisioning
What is this? User Provisioning refers to the automatic synchronisation of users: people defined in your Active Directory (AD) will be automatically synchronized as users in Peripass. E.g. new people in the AD will be added to the users list in Peripass.
Use case? Automatically create e.g. 1000 users of a corporate customer as users / host in Peripass
Main ideas
Single Sign-on + user provisioning support for:
Verified and documented for Microsoft Azure AD (app registered in marketplace, working with open ID Connect & SCIM)
User provisioning principle
Scheduled provisioning at least every 1 hour
Includes: new users, deleted/disabled users, users with new access groups
Users created through provisioning will not receive an invite mail automatically (use case for hosts)
valid & unique email address is required
Role mapping
Choose default role for all provisioned users (use case for hosts)
Set the default language for all users in the tenant’s configuration “Identity provider & provisioning”
Won’t do & known limitiations
Link multiple Identity providers to 1 Peripass tenant (we plan to provide this in the future)
Map different groups in AD to different roles in Peripass
Not validated yet for other Identity providers than Azure Active Directory (Google, Okta, Onelogin, on premise Active Directory).
For SSO we use Open ID Connect. Limitations for custom SSO integrations are mentioned below. We do not support SAML.
For provisioning we use SCIM. Limitations for custom SCIM integrations are unknown.
Azure AD does not allow support for nested AD groups. So only users directly in the group you add will have access. The assignment does not cascade to nested groups.
SSO won’t work on the Yard Operations App. As provisioned users don’t have a local password, only local users are able to login into the Yard Operator App.
User source
There are 2 user types:
Local users: these users log in using email and password.
SSO / Provisioned users: these users are provisioned by your identity provider and log in using SSO.
The user source can be found in the user list.
Multiple email addresses
It is possible to configure email addresses on multiple places in Azure. We only support following email addresses:
user name (default mapped on the Azure user principle name field)
work email (default mapped on Azure mail field - this can be found as part of the contact details)
In case both a user name and a work email is provided, the Peripass will use the work email as go-to mail (for sending emails to users).
If both email addresses are provided, it is possible to use any email address to initiate the authentication from the Peripass login screen.
Typical use case: the user name has an old or unused email (e.g. the group name, and old company name, …), while your daily email contains a different alias. For Peripass it is important to know you alias, since this is the one you will be using to send calendar invites. However the user will be accustomed to using his scim name to login with SSO to any other application in the company.
Custom single sign-on provider
Be aware: integrating using a custom single sign-on provider is not documented, not tested and is not in scope of our support.
Peripass offers the possibility to use a custom single sign-on provider. In this situation provisioning will still happen using the marketplace app, however, single sign-on will happen with a custom provider.
Limitations/requirements:
The custom SSO providor should use the authorization code grant flow (see ietf Oauth spec #4.1 - RFC 6749 - The OAuth 2.0 Authorization Framework (ietf.org)), with response mode "form_post".
The authorization code (C) should be delivered in a form post, encoded as “application/x-www-form-urlencoded”
The access token (received in step E in the flow above) should contain at least the claim/property "preferred_username" containing the username/email address of the user (matching the username/email from the provisioning).
We currently don’t support:
Opaque access tokens
Id tokens
An integration with a custom single sign-on provider is not documented nor tested by Peripass.
Slides for presales
Can be found here: M:\OPS\Sales & Marketing\Peripass\Sales materials\Presales feature slides
Frequently asked questions
We need to get a better view on what permissions the application needs (as a minimum) to function properly and what data will be transferred between both tenants.
Can you provide us with the necessary data so we can pass it on to IT-Sec?
Answer:
The SSO app for user provisioning will be installed with the following permission:
Microsoft Graph: "User.Read" (Sign in and read user profile; see attachment). Documentation: https://docs.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0&tabs=http
Additionally, it will only sync the user data which is defined by the customer in the mapping of synchronized fields (see image below).
