How do I set up SSO?
Our platform has an SSO Authentication framework that integrates with existing Identity provider tools (such as Azure AD and ADFS) and SAML-based tools (such as Okta and Ping).
Setting up SSO with SAML
Setup process
The customer provides SoftwareOne with basic metadata about their IdP. If your SSO tool requires the Assertion Consumer Service URL and Entity ID, please contact SoftwareOne.
SoftwareOne proceeds with a basic setup on the Client Portal IdP and provides the customer with
{connection_name}that'll be used for further configuration.The customer proceeds and finalizes the setup from their side.
All logins to the Client Portal for any of the specified IdP domains will be federated out to the customer's SAML-based IdP.
Setup information required by the Client Portal
IdP Domains: List of email domains, for example
@user.org, for which authentication should be federated out to the customer's IdP.Sign In URL: HTTP-POST or HTTP-Redirect binding.
Sign Out URL
X509 Signing Certificate: In the
.pemor.cerformat.
Technical specification
Capabilities
We support the items listed in the following table:
Supported Protocol Bindings
HTTP-POST & HTTP-Redirect
SAML Authentication Requests signed
Yes (by default)
Sign Request Algorithm
RSA-SHA256 (default) or RSA-SHA1
Sign Request Algorithm Digest
SHA256 (default) or SHA1
Signing Certificate Strength
2048 Bit RSA
IdP-Initiated SSO
Supported, but strongly discouraged
Settings
{connection_name} is a verbatim string that SoftwareOne will provide after receiving the initial configuration settings from you.
Entity ID
urn:auth0:pyc:{connection_name}.
Example: If your connection_name is demo_company, the Entity ID on Production will be
urn:auth0:pyc:demo_company
Assertion Consumer Service URL
https://{idp_base_url}/login/callback?connection={connection_name}
Example: If your connection_name is demo_company, the Assertion Consumer Service URL on Production will be: https://login.pyracloud.com/login/callback?connection=demo_company
Metadata URL
https://login.pyracloud.com/samlp/metadata?connection={connection_name}
Single Logout URL
https://login.pyracloud.com/logout
Single Login URL
We strongly discourage using IdP-Initiated SSO flows because they are vulnerable to Login CSRF attacks. If possible, let the Client Portal initiate the sign-in (and federate out) when required.
Attribute Mappings
The Client Portal requires the following attributes via the specified mappings:
user_id
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
Fallback URL 1: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
Fallback URL 2: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
given_name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Fallback URL: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
family_name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
The attributes must satisfy at least one mapping for all properties above. If your IdP provides values for the required attributes in different claims/namespaces, please provide a list of claims to be used for all attributes above.
Please make sure to provide the attribute values as they are without any modifications.
URLs are sometimes changed by security software, for example, Proofpoint’s Targeted Attack Protection adds urldefense.com at the beginning of links.
Setting up SSO with Azure AD
To set up SSO with the Client Portal via Azure AD, you must complete the following steps. After you've completed these steps, SoftwareOne will enable SSO with your Azure AD.
Setup Process
Step 1: Register the Client Portal with Azure AD
Follow these steps to register the Client Portal as an application inside your Azure subscription:
Sign in to the Microsoft Azure Portal. If you have access to more than one tenant, select your account from the upper right corner. Set your portal session to the Azure AD tenant that you want.
Search for and select Azure Active Directory.
Under Manage, select App registrations.
Select New Registration.
In Register an application, enter a meaningful application name to display to the users, for example, Client Portal.
In Supported account types, select Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant).
In Redirect URI, select the Redirect URI type as Web, and enter your callback URL: https://login.pyracloud.com/login/callback.
Click Register.
Step 2: Create a client secret
SoftwareOne will use the client secret to interact with your Azure subscription on behalf of the created application.
Follow these steps to create a secret:
From the Overview page of the app, select Certificates & secrets > Client secrets > New client secret.
Add a description for your client secret.
Set the expiration date for the secret.
Select Add.
Make a note of the client secret value. Note that the value will not be accessible again after you leave this page.
We recommend that you create a reminder to renew your client secret, at least two weeks before it expires. Once you've created a new secret, provide the value to SoftwareOne so that it can be updated in the system. If your client secret has expired or is no longer valid, you will be unable to sign in to the Client Portal using SSO.
Step 3: Add API permissions
Follow these steps to add permissions that allow read access to users and the user directory:
From the app Overview page, select API permissions.
Under Configured permissions, select Add a permission.
Configure permissions for the Microsoft Graph API.
Once you've selected the API, you'll see the Request API Permissions page.
Enable the following permissions:
Users > User.Read
Directory > Directory.Read.All
Select Add permissions to complete the process.
Enabling the Directory > Directory.Read.All permission is optional. If you want to benefit from future user auto-provisioning, then turn it on. However, for SSO to work, this permission is not required.
Step 4: Collect and forward the information to SoftwareOne
Provide the following information to SoftwareOne. Once received, SoftwareOne can complete the setup and the Client Portal will automatically start forwarding all users of the specified IdP domains to your Azure AD for federated authentication.
Application Client ID
You can find the Application (client) ID on the overview page of the application created in Step 1: Register the Client Portal with Azure AD.
Application Client Secret
Your client secret as created in Step 2: Create a client secret.
Microsoft Azure AD Domain
Your Azure AD domain name. You can find this on your Azure AD directory's overview page in the Microsoft Azure portal.
IdP Domains
A list of all email domains that must be authenticated through the federated Azure AD, for example, @customer.com. Usually 1 domain but can also be multiple.
Technical specification
Capabilities
We support the items listed in the following table:
Identity API
Azure Active Directory (v1) (default) & Microsoft Identity Platform (v2).
Protocol used for federated Sign-In
OpenID Connect (default) or WS Federation.
Settings
Application type
Multitenant / Web
Redirect URI
https://{idp_base_url}/login/callback*
The redirect URI on Production will be:
https://login.pyracloud.com/login/callback
Attribute Mappings
The Client Portal queries the following basic profile attributes from Azure AD:
upn
azure_id
given_name
family_name
nickname
tenantid
oid
email
name
Setting up SSO with ADFS
Setup process
The customer configures their ADFS server according to technical requirements.
The customer provides ADFS Metadata/IdP domains to SoftwareOne.
SoftwareOne will complete the ADFS setup.
Setup information required by the Client Portal
ADFS Metadata Source
Either the URL or the Federation Metadata file. The URL usually ends in /FederationMetadata/2007-06/FederationMetadata.xml.
IdP Domains
List of all email domains that should be authenticated through the federated ADFS server, for example, @customer.com.
Usually 1 domain, but can also be multiple.
Technical specification
Capabilities
We support the items listed in the following table:
Federation Metadata Discovery (Automated Certificate Rollover)
Yes – if ADFS Metadata Source is provided as URL.
Settings
Realm Identifier
urn:auth0:{environment_name}
For example, urn:auth0:pyc on Production.
Endpoint
https://{idp_base_url}/login/callback*
The endpoint URL on Production will be: https://login.pyracloud.com/login/callback
Attribute Mappings
By default, the Client Portal expects the following attributes from ADFS via the specified mappings:
E-Mail-Addresses
E-Mail Address
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Display-Name
Name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
User-Principal-Name
Name ID
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
Given-Name
Given Name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Surname
Surname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Setting up SSO with PingFederate
Setup process
The customer provides Signing Certificates/IdP domains to SoftwareOne.
SoftwareOne will complete the SSO setup.
Setup information required by the Client Portal
PingFederate Server URL.
X509 Signing Certificate in the
.pemor.cerformat.IdP Domains: List of all email domains that should be authenticated through the federated ADFS server (for example,
@customer.com). Usually just one, but can also be multiple.
Technical specification
Attribute Mappings
By default, the Client Portal requires the following attributes via the specified mappings:
user_id
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
Fallback URL 1: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
Fallback URL 2: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
given_name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Fallback URL:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
family_name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
The provided attributes must satisfy at least one mapping for all properties above. If your IdP provides values for the required attributes in different claims/namespaces, please provide a list of claims to be used for all attributes above.
Handling unknown or new users (Ad Hoc Provisioning)
If an email domain is federated out to the user's identity provider, it's possible that the Client Portal will receive sign-in attempts from users who are not set up as Client Portal users.
In such cases, if authenticated users from a federated connection are not Client Portal users, their login to Client Portal will fail with an error message stating that their account is not set up and they don't have access.