Introduction
PyraCloud has a Single sign-On (SSO) Authentication framework that integrates with existing Identity provider tools like Azure AD, ADFS, SAML-based tools like Okta, Ping etc.
This article will guide you through the technical aspects of the configuration.
SAML
Simplified Setup Process
- Customer provides SoftwareONE with basic metadata about their IdP.
- If your SSO tool requires to know the Assertion Consumer Service URL and Entity ID, please contact SoftwareONE to get this input.
- SoftwareONE proceeds with basic setup on the PyraCloud IdP and provides customer with {connection_name} that will be used for further configuration.
- Customer proceeds & finalizes setup on their end.
- All logins to PyraCloud for any of the specified IdP-domains will now be federated out to the users SAML-based IdP.
Required Information for Setup on PyraCloud Side
- IdP Domains
- List of email domains, e.g. @user.org, for which authentication should be federated out to the users IdP
- Sign In URL
- (HTTP-POST or HTTP-Redirect binding)
- Sign Out URL
- X509 Signing Certificate
- in .pem or .cer format
Technical Specifications
Capabilities
We support the following for the below mentioned items, e.g. we support HTTP-POST and HTTP-Redirect for protocol bindings.
| Item | Details |
| 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 will be shared with you once we receive initial configuration settings from you.
| Setting | Value |
| Entity ID | urn:auth0:pyc:{connection_name} e.g. if your connection_name was demo_company, the Entity ID on production would be urn:auth0:pyc:demo_company |
| Assertion Consumer Service URL | https://login.pyracloud.com/login/callback?connection={connection_name} e.g. if your connection_name is demo_company, the assertion consumer service URL on production would 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 from using IdP-Initiated SSO flows as they are, by design, vulnerable to Login CSRF attacks . If possible, users should navigate to PyraCloud (e.g. via https://apps.pyracloud.com/ ) and let PyraCloud initiate the sign-in (and federate out) when required. |
Attribute Mappings
By default, PyraCloud will need the following attributes via the specified mappings from you:
- user_id via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
- (fallback 1) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
- (fallback 2) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- name via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- email via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- given_name via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- (fallback 1) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- family_name via
- 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.
Please make sure to provide the attributes values as they are without any modifications!
URLs are sometimes changed by security software, e.g. Proofpoint’s Targeted Attack Protection adds urldefense.com to the beginning of links.
Azure AD
Simplified Setup Process
- User registers PyraCloud as an application inside their Azure subscription.
- User creates a client secret for this application that can then be used by SoftwareONE to interact with the users Azure subscription on behalf of the created application.
- User adds permissions to the application that allow read access to users and the user directory.
- User forwards client secret & additional information to SoftwareONE (see table below).
- SoftwareONE completes the Single Sign-On setup on PyraCloud side.
Required Information for Setup on PyraCloud Side
| Required Input | Explanation |
| Application Client ID | Can be found in the Azure Portal on the overview page of the application created in Step 1. The field is called “Application (client) ID” |
| Application Client Secret | Created in step 2 |
| Microsoft Azure AD Domain | The customers Azure AD domain name. It can be found on the Azure AD directory’s overview page in the Microsoft Azure portal |
| IdP Domains | List of all email domains that should be authenticated through the federated Azure AD, e.g. @customer.com. Usually one but can also be multiple. |
Technical Specifications
Capabilities
We support the following for the below mentioned items, e.g. Azure Active Directory and Microsoft Identity Platform for Identity API.
| Item | Detail |
| Identity API Used | Azure Active Directory (v1) (default) & Microsoft Identity Platform (v2) |
| Protocol used for federated Sign-In | OpenID Connect (default) or WS Federation |
Settings
| Setting | Value |
| Application type | Multitenant / Web |
| Redirect URI | https://{idp_base_url}/login/callback* i.e. the redirect URI on production is https://login.pyracloud.com/login/callback |
Attribute Mappings
PyraCloud queries basic profile attributes from Azure AD:
- upn
- azure_id
- given_name
- family_name
- nickname
- tenantid
- oid
- name
ADFS
Simplified Setup Process
- User configures their ADFS server according to technical requirements (see below).
- User provides ADFS Metadata/IdP domains to SoftwareONE
- SoftwareONE will complete ADFS setup.
Required Information for Setup on PyraCloud Side
- ADFS Metadata Source
- Either an URL (usually ending in …/FederationMetadata/2007-06/FederationMetadata.xml) or a Federation Metadata File
- IdP Domains
- List of all email domains that should be authenticated through the federated ADFS server (e.g. @customer.com). (Usually just one, but can also be multiple.)
Technical Specifications
Capabilities
We support the following for the below mentioned items.
| Item | Detail |
| Federation Metadata Discovery (Automated Certificate Rollover) | Yes – if ADFS Metadata Source is provided as URL. |
Settings
| Setting | Value |
| Realm Identifier | urn:auth0:{environment_name} e.g. urn:auth0:pyc on production |
| Endpoint | https://{idp_base_url}/login/callback* i.e. the endpoint URL on production is https://login.pyracloud.com/login/callback |
Attribute Mappings
PyraCloud by default expects following attributes from ADFS via the specified mappings:
| LDAP Attribute | Outgoing Claim Type | Namespace |
| E-Mail-Addresses | E-Mail Address | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressm |
| 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 |
Ping Federate
Simplified Setup Process
- User provides Signing Certificates/IdP domains to SoftwareONE
- SoftwareONE will complete the SSO setup.
Required Information for Setup on PyraCloud Side
- PingFederate Server URL
- X509 Signing Certificate
- in .pem or .cer format
- IdP Domains
- List of all email domains that should be authenticated through the federated ADFS server (e.g. @customer.com). (Usually just one, but can also be multiple.)
Technical Specifications
Attribute Mappings
By default, PyraCloud requires the following attributes via the specified mappings:
- user_id via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
- (fallback 1) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
- (fallback 2) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- name via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- email via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- given_name via
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- (fallback 1) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- family_name via
- 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
Things to Watch Out For
Handling Unknown / New Users (Ad Hoc Provisioning)
If an email domain is federated out to the users identity provider, it is possible that PyraCloud will receive sign-in attempts from users which are not setup as PyraCloud users.
In that case, if authenticated users from a federated connection are not PyraCloud users, their login to PyraCloud will fail with an error message stating that their account is not setup and they do not have access.