1. Home
  2. Setup
  3. Single Sign-on (SSO) Integration

Single Sign-on (SSO) Integration

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

  1. Customer provides SoftwareONE with basic metadata about their IdP.
    1. If your SSO tool requires to know the Assertion Consumer Service URL and Entity ID, please contact SoftwareONE to get this input.
  2. SoftwareONE proceeds with basic setup on the PyraCloud IdP and provides customer with {connection_name} that will be used for further configuration.
  3. Customer proceeds & finalizes setup on their end.
  4. 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.

ItemDetails
Supported Protocol BindingsHTTP-POST & HTTP-Redirect
SAML Authentication Requests signedYes (by default)
Sign Request AlgorithmRSA-SHA256 (default) or RSA-SHA1
Sign Request Algorithm DigestSHA256 (default) or SHA1
Signing Certificate Strength2048 Bit RSA
IdP-Initiated SSOSupported, but strongly discouraged.

Settings

{connection_name} is a verbatim string that will be shared with you once we receive initial configuration settings from you.

SettingValue
Entity IDurn: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 URLhttps://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 URLhttps://login.pyracloud.com/samlp/metadata?connection={connection_name}
Single Logout URLhttps://login.pyracloud.com/logout
Single Login URLWe 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

  1. User registers PyraCloud as an application inside their Azure subscription.
  2. 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.
  3. User adds permissions to the application that allow read access to users and the user directory.
  4. User forwards client secret & additional information to SoftwareONE (see table below).
  5. SoftwareONE completes the Single Sign-On setup on PyraCloud side.

Required Information for Setup on PyraCloud Side

Required InputExplanation
Application Client IDCan 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 SecretCreated in step 2
Microsoft Azure AD DomainThe customers Azure AD domain name. It can be found on the Azure AD directory’s overview page in the Microsoft Azure portal
IdP DomainsList 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.

ItemDetail
Identity API UsedAzure Active Directory (v1) (default) & Microsoft Identity Platform (v2)
Protocol used for federated Sign-InOpenID Connect (default) or WS Federation

Settings

SettingValue
Application typeMultitenant / Web
Redirect URIhttps://{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
  • email
  • 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.

ItemDetail
Federation Metadata Discovery
(Automated Certificate Rollover)
Yes – if ADFS Metadata Source is provided as URL.

Settings

SettingValue
Realm Identifierurn:auth0:{environment_name}
e.g. urn:auth0:pyc on production
Endpointhttps://{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 AttributeOutgoing Claim TypeNamespace
E-Mail-AddressesE-Mail Addresshttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressm
Display-NameNamehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
User-Principal-NameName IDhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
Given-NameGiven Namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
SurnameSurnamehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Ping Federate

Simplified Setup Process

  1. User provides Signing Certificates/IdP domains to SoftwareONE
  2. 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.

Updated on March 28, 2023

Was this article helpful?

Related Articles