Skip to main content

Integration Guide for Shibboleth IDP

  • Updated

Introduction

This guide provides information on how to:

  • Configure Shibboleth IdP as a SAML Proxy with Beyond Identity as delegate IdP.



Prerequisites

  • Ensure that you have a working Shibboleth IdP instance version 4.0 or 4.1.
  • A working SP configured on the Shibboleth IdP.
  • The Shibboleth IdP must have a data connector (LDAP or database) configured for attribute resolution. There must be a "joining" attribute shared between Shibboleth and Beyond Identity used to look up additional attributes required by the SP. This attribute must be unique and (preferably) immutable in the directory or database. All of the examples in this guide will use "uid" as the unique user directory attribute.

 

NOTE: This guide makes no assumptions about the existing Shibboleth IdP authentication configuration or customized attributes and schemas. The examples given in the guide are based on the examples in the how-to article in Shibboleth IdP 4.1 documentation "Using SAML Proxying to Another IdP" (see https://shibboleth.atlassian.net/wiki/spaces/KB/pages/1459979597/Using+SAML+Proxying+to+another+IdP). Please refer to Shibboleth documentation for examples specific to your configuration (mileage may vary).






Beyond Identity Configuration

Ensure that the Admin Console Passwordless Login option has been enabled on your Beyond Identity tenant account, and that you have enrolled a valid credential for admin console login.

 

Information you will need during deployment

Information to provide to the Beyond Identity Field Team

Your Company Name  

Your Shibboleth IDP Entity ID

e.g., https://sso.shibboleth.example.edu

  

Beyond Identity Admin Console Application credentials

SSO Client Id

SSO Client Secret

  

Beyond Identity User Console Application credentials

SSO Client Id

SSO Client Secret

 This will be updated by customer directly in Beyond Identity Admin Console UI.

(Optional) A logo for your corporation

Logo requirements:

300 x 150 pixels or less

File size of 10kb or less

File types accepted: SVG, PNG, JPG, or GIF

  

 

 

Document Conventions

Config Files (.xml, .properties, .props, code blocks) - monospace font in shaded text box.

Example:

#idp.service.attribute.registry.resources = shibboleth.AttributeRegistryResources

#idp.service.attribute.registry.failFast = false

idp.service.attribute.registry.checkInterval = PT15M

# Default control of whether to encode XML attribute data with xsi:type

idp.service.attribute.registry.encodeType = false

 

Inline code / CLI / commands / variables - bold monospace font over shaded background.

Example: 

${idp.home}/bin/status.sh



Important Variables

${idp.home} - The default installation location of Shibboleth IdP. In this guide, the absolute path to ${idp.home} is /opt/shibboleth-idp/.

 

 

Beyond Identity Configuration

1. In the Beyond Identity Admin Console, navigate to Integrations -> SAML -> click Add SAML Connection. Configure the settings for the Shibboleth instance:
SP Single Sign On URL: https://${MY-SHIBBOLETH-HOSTNAME}/idp/profile/Authn/SAML2/POST

SP Audience URI:  https://${MY-SHIBBOLETH-ENTITY-ID}

Name ID Format:  emailAddress

Subject User Attribute: Email 
      **NOTE: Any source Subject attribute may be used as long as it provides immutability and uniqueness in the target directory. This attribute will be used to lookup a unique user in the target directory. 

Request Binding: http post

Signed Response: enabled

Example:

Under the Attribute Statement, add uid with a Name format of basic, and map from either:  {{Email}} or {{ExternalId}} — whichever is mapped to uid on the Shibboleth directory instance.

2. Save Changes then click on the </> Download Metadata button and save the metadata file to ${idp.home}/conf/idp-beyond-identity-metadata.xml on the Shibboleth instance.

 

** ADd section for SAML authn to Admin & User consoles

 

Shibboleth Configuration

Update Shibboleth IdP metadata to support the SP role with Beyond Identity as delegate IdP

The IdP must act as a SAML SP when operating as a SAML proxy. The following configuration allows Shibboleth IdP to accept the upstream IdP's SAML protocol reponses.

 

  1. Add the following example <SPSSODescriptor> block to ${idp.home}/conf/idp-metadata.xml with your Shibboleth URL. Add the <SPSSODescriptor> block anywhere within <EntityDescriptor>. The signing and encryption certificates may be assigned as needed. Replace MY-IDP-HOSTNAME with your Shibboleth base URL, and MY-SHIBBOLETH-ENTITY-ID with the entityID value from your IdP metadata file.
    Example:

<EntityDescriptor  xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://MY-SHIBBOLETH-ENTITY-ID"

 ...omitted for brevity...>


   <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

      <KeyDescriptor use="signing">

           <ds:KeyInfo>

                   <ds:X509Data>

                       <ds:X509Certificate>

…<***OPTIONAL - Add Signing Cert here>...

                       </ds:X509Certificate>

                   </ds:X509Data>

           </ds:KeyInfo>


       </KeyDescriptor>


       <KeyDescriptor use="encryption">

           <ds:KeyInfo>

                   <ds:X509Data>

                       <ds:X509Certificate>

...<***OPTIONAL - Add Encryption Cert here>...

                       </ds:X509Certificate>

                   </ds:X509Data>

           </ds:KeyInfo>

       </KeyDescriptor>

       <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://MY-IDP-HOSTNAME/idp/profile/Authn/SAML2/POST/SSO" index="0"/>

   </SPSSODescriptor>


...

</EntityDescriptor>

 

2. Add the following to ${idp.home}/conf/metadata-providers.xml anywhere within the <MetadataProvider id="ShibbolethMetadata" ...> tag:

<MetadataProvider id="beyond-identity-idp"

    xsi:type="FilesystemMetadataProvider"

    metadataFile="/opt/shibboleth-idp/metadata/idp-beyond-identity-metadata.xml">

</MetadataProvider>

 

3. Enable the SAML Authentication flow. This enables the Beyond Identity IdP to be delegated to as part of the SAML flow. The attribute filter policy must also be updated to allow the IdP to ingest the attributes from the delegate IdP.

 

  1.  Edit ${idp.home}/conf/authn/saml-authn-config.xml to set the upstream Beyond Identity IDP. The c:target value can be obtained from the ${idp.home}/metadata/idp-beyond-identity-metadata.xml file as the entityID value.
    Example (in bold):

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"

       xmlns:context="http://www.springframework.org/schema/context"

       xmlns:util="http://www.springframework.org/schema/util"

       xmlns:p="http://www.springframework.org/schema/p"

       xmlns:c="http://www.springframework.org/schema/c"

       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd

                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd

                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"

                           

       default-init-method="initialize"

       default-destroy-method="destroy">


    <bean id="shibboleth.authn.SAML.discoveryFunction"

          parent="shibboleth.Functions.Constant"

c:target="https://auth.byndid.com/saml/v0/abcdef01-0123-4567-89ab-cdecf0123456/sso/metadata.xml" />

...

</beans>
  1. Enable the SAML IdP flow by adding SAML to the authentication flow.
    Edit ${idp.home}/conf/idp.properties.
    Add SAML to the list of values in idp.authn.flows.  The values are pipe-delimited (|).

Example:

idp.authn.flows = SPNEGO|Password|SAML

 

  1. Update ${idp.home}/conf/attribute-filter.xml. Add the following anywhere within the <AttributeFilterPolicyGroup> tag. Replace issuer value with your Beyond Identity SAML entity ID:

<AttributeFilterPolicy id="saml-proxy-pass-through">

    <PolicyRequirementRule xsi:type="Issuer" value="https://auth.byndid.com/saml/v0/abcdef01-0123-4567-89ab-cdecf0123456/sso/metadata.xml" />

    <AttributeRule attributeID="uid" permitAny="true" />

</AttributeFilterPolicy>



4. Subject Canonicalization must be performed after ingesting the "uid" in attribute-filter.xml. This requires a new <AttributeDefinition> element in ${idp.home}/conf/attribute-resolver.xml. It also requires the attribute resolver to map in internal attribute name, proxied-uid in this case, as the joining attribute. Once that is done, this attribute will be used for the Data Connector lookup defined in attribute-resolver.xml.

 

NOTE: These steps do not accommodate for all of the Subject Name Identifier (NameID) combinations currently configured on your Shibboleth instance. It may be configured for transient or persistent NameID, and individual SPs may require either. These steps only apply to persistent identifiers. Mileage may vary.

 

  1. In ${idp.home}/conf/attribute-resolver.xml add the following attribute definition anywhere within the <AttributeResolver .../> tag:

<AttributeDefinition xsi:type="SubjectDerivedAttribute"

    forCanonicalization="true"    

    principalAttributeName="uid"

    id="proxied-uid"

/>

 

  1. In ${idp.home}/conf/c14n/subject-c14n.properties, verify that the "joining" attribute (uid in the examples) has been added to the idp.c14n.attribute.attributesToResolve setting.
    Example:

idp.c14n.attribute.attributesToResolve = eduPersonPrincipalName,mail,uid,...

 

  1. This step assumes that a Data Connector of type LDAPDirectory has already been configured. If necessary, update the existing LDAP filter in ${idp.home}/conf/ldap.properties in the setting idp.attribute.resolver.LDAP.searchFilter.
    Example:
idp.attribute.resolver.LDAP.searchFilter  = (|(eduPersonPrincipalName=$resolutionContext.principal)(mail=$resolutionContext.principal)(isMemberOf=CN=Beyond Identity Users,OU=Groups,OU=People,DC=example,DC=edu)(uid=$resolutionContext.principal))

 

  1. In ${idp.home}/conf/c14n/subject-c14n.xml, enable the SAML2ProxyTransform post-login canonicalization flow. This enables the IdP to map the principal directly from the incoming SAML 2.0 NameID from Beyond Identity. Add the following bean anywhere within the <util:list id="shibboleth.PostLoginSubjectCanonicalizationFlows"> tag:

<util:list id="shibboleth.PostLoginSubjectCanonicalizationFlows">

    <ref bean="c14n/SAML2ProxyTransform" />

   ...

</util:list>



5. At this point, any SP can be wired to use a passwordless flow by assigning the SAML authentication flow in ${idp.home}/conf/relying-party.xml.

For example:

<bean parent="RelyingPartyByName" c:relyingPartyIds="https://sp.example.com/SAML2/SP">

      <property name="profileConfigurations">

          <list>

            <bean 

              parent="SAML2.SSO" 

                         p:authenticationFlows="#{{'SAML'}}"

              p:encryptAssertions="false" 

              p:encryptNameIDs="false" />

          </list>

      </property>

</bean>

 

SCIM Provisioning

Users from the authoritative source directory queried by Shibboleth may be provisioned to the Beyond Identity User directory using the standard SCIM 2.0 protocol. This guide makes no assumptions about the backend directory used by Shibboleth or its SCIM capabilities. However, the examples given in this guide reference a "Beyond Identity Users" group in both the LDAP filter and "Setting up test users" section below. 

The respective SCIM 2.0 API endpoints for user and groups are:

https://api.bynid.com/v0/users

https://api.byndid.com/v0/groups

 

The tenant API key provided by your Beyond Identity sales team must be included as an HTTP Bearer token for authorization to these APIs.

 

For more information on SCIM 2.0, please refer to:

http://www.simplecloud.info/

https://datatracker.ietf.org/doc/html/rfc7644

 

Setting up test users

 

User Enrollment

  1. To enroll a user in the Beyond Identity experience, assign the user to the "Beyond Identity Users" LDAP group in your directory.

 

  1. The enrolled user will receive an email from Beyond Identity welcoming them to the new Identity Provider.
    1. See image below for reference:

 

 

  1. Each enrolled user will be asked to follow the two steps below:
    1. Step 1: Download the Beyond Identity Authenticator to their device.
      1. When the user clicks “View Download Options”, the Beyond Identity Authenticator downloads page will open in a browser with all supported platforms displayed. The user should download and install the Beyond Identity Authenticator on their device if they have not already.
      2. Now that the user has the Authenticator installed on their device, they should proceed to Step 2 as there is not yet a user credential associated with the Authenticator on that device.
    2. Step 2: Register their Credential in the Beyond Identity IdP.
      1. By clicking on Step 2 “Register New Credential”, the user’s credential will get enrolled in the Beyond Identity service on the back end. On the front end, users who click Step 2 will be taken to the Beyond Identity Authenticator where they will see the progress of their credential registration. Once completed, the user will see a credentials in the Authenticator. 
      2. See example image below:

 



 

References

https://shibboleth.atlassian.net/wiki/spaces/KB/pages/1459979597/Using+SAML+Proxying+to+another+IdP

 

https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1282539600/SAMLAuthnConfiguration

 

https://shibboleth.atlassian.net/wiki/spaces/KB/pages/1467056889/Using+SAML+Proxying+in+the+Shibboleth+IdP+to+connect+with+Azure+AD










Related articles

Comments

0 comments

Please sign in to leave a comment.