Shibboleth Integration

Shibboleth is an open-source implementation for identity management and federated identity-based authentication and authorization (or access control) infrastructure based on Security Assertion Markup Language (SAML). This allows for cross-domain single sign-on and removes the need for content providers to maintain end-user credentials. Identity providers (IdPs) supply user information, while service providers (SPs) consume this information and give access to secure content.

MIRACL Trust could be integrated either with the Shibboleth SP through the MIRACL Trust SSO IdP or directly to the Shibboleth IdP using the Apache OIDC module. More information about the integration with our SSO service could be read here. This page contains information about the integration of the Shibboleth IdP with the MIRACL Trust platform.

# MIRACL Trust Application Setup

An application on the MIRACL Trust Portal is required. It is used by the Apache OpenID Connect module to authenticate end users against the MIRACL Trust platform being the OpenID Connect Provider.

Learn how to register a new MIRACL Trust app here.

# Shibboleth Setup

We suggest you to assure that your Shibboleth IdP and SP are properly setup and working before starting the integration with MIRACL Trust.

Note that the instructions here are made for Apache2 and OpenID Connect authentication module for Apache v.2.3.10.2 under ubuntu 20.04. If you install it in another environment, please, review the module page for instructions.

The first step is to install and enable the OpenID Connect module for Apache so you can set it up to authenticate against MIRACL API.

apt-get update && apt-get install -y libapache2-mod-auth-openidc
# create an endpoint /oidc to handle the mod_auth_openidc callback
mkdir /var/www/html/oidc/
touch /var/www/html/oidc/index.html
chown www-data:www-data -R /var/www/html/oidc/

Create a configuration /etc/apache2/conf-available/oidc.conf for the module and fill the required data.

  <Location /oidc>
     AuthType openid-connect
     Require claim "sub~\w+\@example\.com$"
   </Location>
  <Location /idp/profile/Shibboleth/SSO>
    AuthType openid-connect
    Require claim "sub~\w+\@example\.com$"
  </Location>
  <Location /idp/profile/SAML2/POST/SSO>
    AuthType openid-connect
    OIDCPreservePost On
    Require claim "sub~\w+\@example\.com$"
  </Location>
  <Location /idp/profile/SAML2/POST-SimpleSign/SSO>
    AuthType openid-connect
    OIDCPreservePost On
    Require claim "sub~\w+\@example\.com$"
  </Location>
  <Location /idp/profile/SAML2/Redirect/SSO>
    AuthType openid-connect
    Require claim "sub~\w+\@example\.com$"
  </Location>

<IfModule mod_auth_openidc.c>
   OIDCRedirectURI https://idp.example.com/oidc/callback
   OIDCProviderIssuer https://api.mpin.io
   OIDCProviderMetadataURL https://api.mpin.io/.well-known/openid-configuration
   OIDCProviderJwksUri https://api.mpin.io/oidc/certs
   # generate and replace <RANDOMSTRING> (for example: openssl rand -base64 32)
   OIDCCryptoPassphrase <RANDOMSTRING>
   OIDCClientID <YOUR_CLIENT_ID>
   OIDCClientSecret <YOUR_CLIENT_SECRET>
   OIDCScope "openid email profile"
   OIDCProviderTokenEndpointAuth client_secret_post
   OIDCResponseType "code"
   OIDCRemoteUserClaim "sub"
   OIDCResponseMode "query"
   OIDCJWKSRefreshInterval 300
</IfModule>

You need to fill in the following data to set up MIRACL Trust as an identity provider:

  • Every location accepts only authentication with claims sub which ends with @example.com. Update it for your case.
  • OIDCRedirectURI is a vanity URL that must point to a path protected by mod_auth_openidc but must NOT point to any content
  • OIDCCryptoPassphrase is used for session/state encryption purposes
  • For <YOUR_CLIENT_ID> fill in the Client ID you received from the MIRACL Trust Application setup
  • For <YOUR_CLIENT_SECRET> fill in the Client Secret you received from the MIRACL Trust Application setup

Ensure that the OIDCRedirectURI is the same as the Redirect URL that you filled during the MIRACL Trust Application setup.

The mod_auth_openidc and its configuration should be enabled for Apache by:

a2enmod auth_openidc
a2enconf oidc

The Shibboleth IdP authentication flow should be set to RemoteUserInternal in the file /opt/shibboleth-idp/conf/idp.properties:

idp.authn.flows=RemoteUserInternal

In this version of the mod_auth_openidc it was essential to set the authentication headers in /opt/shibboleth-idp/conf/authn/remoteuser-internal-authn-config.xml to:

<util:constant id="shibboleth.authn.RemoteUser.checkRemoteUser" static-field="java.lang.Boolean.FALSE"/>
<util:list id="shibboleth.authn.RemoteUser.checkHeaders">
    <value>OIDC_CLAIM_sub</value>
</util:list>

After restart of Apache and the Shibboleth IdP when you open your SP login endpoint, you should be navigated to MIRACL Trust login page.