1. Home
  2. Setup
  3. Single Sign-on Integration

Single Sign-on Integration

Introduction

PyraCloud has a new Single Sign-On Authentication framework that integrates with existing Identity provider tools like Azure AD, ADFS, SAM-based tools like Okta, Ping etc.

This article will guide you through the technical aspects of the configuration.

Environments

The following properties and values refer to environment settings that are referenced later in the document.

PropertyProductionQA (UAT)Test
{environment_name}pycpyc-qapyc-test
{idp_base_url}login.pyracloud.com login-qa.pyracloud.com login-test.pyracloud.com

SAML

Simplified Setup Process

  1. User provides SoftwareONE with basic metadata about their IdP.
  2. SoftwareONE proceeds with basic setup on the PyraCloud IdP and provides user with the connection_name that will be used for further configuration.
  3. User 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. For 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 is given to to the federating party after receiving the initial configuration from them. See Environments table.

SettingValue
Entity IDurn:auth0:{environment}:{connection_name}
e.g. if your connection_name is demo_company, the Entity ID on production would be urn:auth0:pyc:demo_company
Assertion Consumer Service URLhttps://{idp_base_url}/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://{idp_base_url}/samlp/metadata?connection={connection_name}
Single Logout URLhttps://{idp_base_url}/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

PyraCloud by default expects following attributes via the specified mappings from the customer:

  • 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

  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, who can then complete the Single Sign-On setup on PyraCloud side.

Required Information for Setup on PyraCloud Side

  • 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
  • Microsoft Azure AD Domain
  • The customers Azure AD domain name.
    • This 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 just one, but can also be multiple.)

Technical Specifications

Capabilities

We support the following for the below mentioned items. For e.g. we support 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*
e.g. the redirect uri on production would be 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*
e.g. the endpoint url on production would be 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 ADFS 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

PyraCloud by default expects 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 a whole email domain is federated out to the users identity provider, it is possible that PyraCloud will receive sign-in attempts from people that are not setup to use the platform.

Ad-Hoc access provisioning to those accounts is possible, but by default not turned on.

If an authenticated user coming from a federated connection is not setup inside PyraCloud, their login to the platform will fail with an error message telling them that their account is not setup and they do not have access.

Updated on November 13, 2020

Was this article helpful?

Related Articles