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.
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.