SSO Configuration Guide
Configure Single Sign-On (SSO) for Smartflow using your bank's identity provider. Smartflow supports both SAML 2.0 and OpenID Connect (OIDC) protocols.
Prerequisites
- Smartflow instance deployed and accessible.
- Admin access to your Identity Provider (IdP) — e.g., Azure AD, Okta, Ping Identity.
- Admin access to Smartflow's Settings → Authentication page.
- Network connectivity between Smartflow and your IdP (verify firewall rules).
SAML 2.0 Configuration
Smartflow Service Provider (SP) Details
Provide these values to your IdP administrator:
| Parameter | Value |
|---|---|
| Entity ID (SP) | https://{your-instance}.smartflow.io/auth/saml/metadata |
| ACS URL | https://{your-instance}.smartflow.io/auth/saml/callback |
| SLO URL | https://{your-instance}.smartflow.io/auth/saml/logout |
| NameID Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Signature Algorithm | RSA-SHA256 |
IdP Configuration Parameters
Collect these values from your IdP and enter in Smartflow:
| Parameter | Description |
|---|---|
| IdP Entity ID | Your IdP's entity identifier |
| SSO URL | IdP's Single Sign-On endpoint |
| SLO URL | IdP's Single Logout endpoint (optional) |
| x509 Certificate | IdP's signing certificate (PEM format) |
Attribute Mapping
| SAML Attribute | Smartflow Field | Required |
|---|---|---|
email | User email | Yes |
given_name | First name | Yes |
family_name | Last name | Yes |
groups | Role assignment | Recommended |
OpenID Connect (OIDC) Configuration
Smartflow OIDC Parameters
| Parameter | Value |
|---|---|
| Redirect URI | https://{your-instance}.smartflow.io/auth/oidc/callback |
| Post-Logout Redirect | https://{your-instance}.smartflow.io |
| Scopes | openid profile email |
IdP Configuration Parameters
| Parameter | Description |
|---|---|
| Client ID | Application/client ID from your IdP |
| Client Secret | Application secret (stored encrypted) |
| Issuer URL | https://{your-idp}/.well-known/openid-configuration |
Testing
- Test login: Access Smartflow and verify redirect to your IdP login page.
- Test user attributes: After login, verify user name and email appear correctly in Smartflow.
- Test role mapping: Verify that IdP group membership maps to the correct Smartflow role.
- Test logout: Click logout in Smartflow and verify session is terminated at the IdP.
- Test session expiry: Wait for session timeout and verify re-authentication is required.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Redirect loop after login | ACS URL mismatch | Verify ACS URL in IdP matches Smartflow SP details |
| "Invalid signature" error | Certificate mismatch | Re-download IdP certificate and update in Smartflow |
| User created without role | Group attribute not mapped | Configure groups claim in IdP and Smartflow attribute mapping |
| Login works but logout doesn't | SLO not configured at IdP | Configure SLO URL at IdP or disable SLO in Smartflow |
| "User not found" after login | Email domain not allowlisted | Add user's email domain to Smartflow's allowed domains |
info
For detailed troubleshooting, see the Access and Permissions Runbook.