SSO

APIO core supports SSO (Single Sign-On) via a bunch of protocols.

Single sign-on (SSO) is an authentication scheme that allows a user to log in with a single ID and password to any of several related, yet independent, software systems. True single sign-on allows the user to log in once and access services without re-entering authentication factors.

It allows users to authenticate themselves on one platform and then use the same credentials to access other platforms within the same organization. So they don't need to be provisioned or authenticated on each platform.

Login page

The login page may display an SSO button to allow users to login via SSO if the provider entry is configured.

The button label is Login with followed by the name of the provider entry.

Extra rules

Even if the IdP accept the authentication, APIO core may reject it if the user doesn't match some extra rules. (e.g. the user is not in the correct group / organization)

The rules are simple expressions based on the element of the token IdP decoded. (e.g hd == 'mycompany.com' when the attribute hd is returned by the IdP in the protocol OIDC)

User creation rules

When a user is authenticated via SSO, APIO core may create the user if it doesn't exist.

The rules are a mapping between the elements of the token IdP decoded and user profiles definitions.

WARNING

If no rules exists or no rule match, the user is not created. And the authentication is rejected.

Protocols

OpenID Connect

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0 that can be used to securely sign users in to web applications.

Attribute	Description
Auth. endpoint	The URL of the authentication endpoint.
Scope	The scope of the authentication.
Token endpoint	The URL of the token endpoint.
Client ID	The client ID.
Client secret	The client secret.
Redirect URI	The redirect URI.
Token issuer	The issuer of the token.
Provider	Some specifics for certain implementation.

SAML

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider.

In SAML, the Service Provider (SP) is the system or application that users want to access. It relies on an Identity Provider (IdP) to authenticate users and verify their identity. Once authentication is successful, the IdP sends a SAML assertion to the SP, allowing the user to log in without entering credentials again. Examples of SPs include cloud applications, enterprise portals, and SaaS platforms.

In our context, APIO Core acts as the Service Provider (SP), while the Identity Provider (IdP) is the external system responsible for authenticating users.

The SSO authentication flow proceeds as follows:

1. The user accesses any Core URL (initial request URL).
2. If no active session exists, the Core redirects the user to the login form.
3. The user clicks the "Login with SAML" button.
4. The Core constructs the SAML request URL, embedding the initial request URL for redirection after authentication. This SAML request URL is built based on the parameters defined in the IdP SSO configuration.
5. The user is redirected to the SAML request URL.
6. If not already authenticated, the IdP presents a login form.
7. The user enters credentials and submits the form.
8. Upon successful authentication, the IdP redirects the user via a POST request to the post-login URL (also known as the assertion consumer service URL or ACS) specified in the SAML request URL.
9. The Core validates the response and the initial request URL (contained in RelayState) based on its IdP SSO configuration.
10. The browser is redirected to the initial request URL.

The following diagram provides a visual representation of the flow:

INFO

The SAML request URL consists of multiple parameters, including SAMLRequest, which contains the post-login URL, and RelayState, which holds the initial request URL.

Below is an example of a base64-decoded SAMLRequest, formatted for clarity:

<samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="id-4dbb382821648fcfa8c90c22ce490b9f9d0a06a5" Version="2.0" IssueInstant="2025-03-31T07:17:08.816Z" Destination="https://idp.provider.com/realms/rben/protocol/saml" AssertionConsumerServiceURL="http://apio.com/api/v01/auth/login_rben_saml" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
  <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">apio-dev</saml:Issuer>
  <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" AllowCreate="true"/>
</samlp:AuthnRequest>

To configure a SAML Identity Provider (IdP), the following parameters must be set in the Core configuration:

For the Identity Provider (IdP):

Attribute	Description
Metadata XML	Provided by the IdP, this XML contains the EntityDescriptor defining the IdP's login URL and the certificate used to verify the integrity and authenticity of SAML assertions generated by the IdP.

For the Service Provider (SP):

Attribute	Description
Entity Id	The SP uses the Entity ID to identify itself to the IdP during the SAML authentication request process.
Assertion Consumer Service (ACS) URL	The endpoint where the IdP redirects the user after authentication, using a POST binding. This URL is structured as https://<host>/api/v01/auth/login_<sso_name> where <sso_name> corresponds to the name of this SSO configuration.
x509 Certificate	Used by the IdP to verify the signature created by the SP, which is included in the Signature and SigAlg URL parameters when redirecting the user to the IdP.
x509 Private Key	Used by the SP to sign SAML requests before sending them to the IdP.
Valid Redirects	A list of allowed redirection URLs that are validated against the RelayState parameter when the IdP redirects the user back to the Core system.

INFO

The SP certificate and private key can either be provided by the IdP or generated on the SP side and communicated to the IdP (in which case, the private key should not be shared). It’s important to note that some IdPs do not check or enforce the use of signed SAML requests. In such cases, it is possible to create a self-signed certificate, as this parameter is mandatory. The IdP will simply ignore the certificate if it’s not used for validation.

WARNING

Both the Assertion Consumer Service (ACS) URL and the valid redirect URLs must be the publicly accessible URLs that the end-user can reach during the login process. This is because the browser is responsible for making requests to these URLs. Therefore, if the core application is deployed behind a reverse proxy, these URLs must align with the publicly exposed URLs to ensure proper functionality.

Webseal

WebSeal is a reverse proxy server that provides authentication and authorization services for a web application.

This proxy adds HTTP headers in the client traffic with the user information. (e.g. iv-user)

APIO core trusts these headers only if the Webseal proxy IP appears in the list of trusted source IPs.

Attribute	Description
HTTP header with client IP	Used to fetch the (webseal) client IP address when the instance is behind some reverse proxy. (e.g X-Real-IP)
Trusted source IPs	List of trusted source IPs.

Soap Token

Proprietary protocol used by custom company implementation of IdP.

Broadsoft

Broadsoft is integrated in the regular login API of APIO core.

The extra rules and user creation rules are evaluated with the following attributes:

• client_ip is the IP of the client.
• is_client_ip_private is true if the client IP is in a private range.
• auth is the answer from the Broadsoft gateway login API.
• is_system is true if the user is a system user (either on Broadsoft or on the core).

Samples

Prevent system level users to use Broadsoft SSO

Resellers (access_type == 1) is a special kind of users that can manage several tenants, so they are created at system level but restricted by the Broadsoft gateway.

not is_system or auth.profile.access_type == 1

Prevent Broadsoft system and provisioning users to use Broadsoft SSO from public IPs

(auth.profile.broadsoft_type != "System" or auth.profile.broadsoft_type != "Provisioning") or is_client_ip_private

Authorisation handler

Attribute	Description
Proxies	Map the proxies allowed to authenticate via this provider. And to which gateway they need to go.
Authorisation handler	The authorisation handler to use. When set to map to broadsoft user, the Username mapping template can be used to transform the SSO username into Broadsoft username and attributes from Broadsoft bound to the APIO core user.

INFO

The system level flag in the User creation rules are not available for Broadsoft users auto-provisioning.
Broadsoft users can still be created (and manually granted with the system flag) but cannot manage the platform at system level automatically.
Past experience shows that the risk is too high to allow this.