Plus - SSO (SingleSignOn)

Introduction 

Papirfly uses a common application, Keycloak, to manage SSO setups with clients. Our SSO executes an authentication process where we act as the Service Initiator and request approval from your IdP to grant user access.

We also handle user provisioning by creating the user within our platform, where all access is managed.

SSO Process

The process begins by defining the SSO source on the client side and determining which protocol will be used. In general, the majority of clients use SAML or OIDC, while some opt for a simpler EntraID API connection (formerly known as Azure AD).

Regardless of the protocol, the process involves sharing specific data between the client and us to set up the initial connection. During this phase, we also discuss the unique identifier for a user.

Once both sides have completed the configuration, an initial test is conducted to verify that the user claims are transmitted as expected. Any necessary reconfiguration is then performed to align with the required data before moving into production.

Step by step guide

Follow these steps on your side (SAMPLE for Entra ID):

1. Go to Applications > Enterprise applications > Enterprise applications | All applications 
2. Create a new application (using the + New application button)
3. Search for Papirfly SSO in the Microsoft Entra Gallery and select the Papirfly application:
   • 

4. Give a conventional name to the application and click on the Create button.

5. Under the application you just created, go to Single sign-on on the side panel, then use the following values under the Basic SAML Configuration section:

6. Identifier (Entity ID): <will be given by Papirfly>

7. Reply URL (Assertion Consumer Service URL), can be multiple values: <will be given by Papirfly>

8. Sign on URL:  <will be given by Papirfly>

9. Save

10. Go to SAML Certificates, copy the App Federation Metadata Url

    • Alternatively; go to the section “Set up <your application name>” and send over the  Login and Logout URL values

11. Share either value with Papirfly

SSO Data

Since the Papirfly platform relies heavily on notifications, an email address is required. While a username can be different, providing an email address is mandatory.

• Minimal requirements:
• Unique Identifier
• Email Address (can be Unique identifier as well)
• First Name
• Last name

Preferred user information

• Display Name
• Anything else needed to be stored on user

We offer options for the authorization flow based on user claims, which will be discussed during the discovery phase.

Claim example

For ID and email address:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

For personal info:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennames
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname

Generic instructions for the different protocols

SAML

Papirfly will provide the client with the ACS URL and EntityID. Once the client has completed their setup, they will provide Papirfly with the federation metadata XML file or the Single Sign-On Service URL.

The ACS URL depends on the chosen domain (refer to how Papirfly offers domain options to its clients). Papirfly will also share the following information:

ACS URL (2x)

https://app.papirfly.com/keycloak/realms/<unique clientID>/broker/saml/endpoint
https://<client domain for solution>/keycloak/realms/<unique clientID>/broker/saml/endpoint

EntityID:

https://<client domain for solution>/keycloak/realms/<unique clientID>

Papirfly receives the client configuration, makes the necessary adjustments, and then provides the client with a test URL to trigger the SSO.

OIDC

Papirfly will provide the client with a callback address. 

Callback-URLs
https://app.papirfly.com/keycloak/realms/pf-12144/broker/oidc/endpoint
https://<client domain for solution>/keycloak/realms/<unique clientID>/broker/oidc/endpoint

The client will send over their discovery URL to papirfly: /.well-known/openid-configuration
Client ID and Client Secret

Papirfly receives the client configuration, make some adjustments and then provide the client with a test URL that will trigger SSO.

EntraID API

We provide a callback URL:
https://<client domain for solution>/keycloak/realms/<unique clientID>/broker/microsoft/endpoint
And the client sends us Tenant, Application (Client ID) and Client Secret.

Papirfly receives the client configuration, makes some adjustments, and then provides the client with a test URL to trigger the SSO.