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 user credentials. Identity providers (IdPs) supply user information, while service providers (SPs) consume this information and give access to secure content.

MIRACL Platform 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 platform.

MIRACL Trust Application setup

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

Learn how to register a new MIRACL 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 the MIRACL platform.

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 MIRACL_CLIENT_ID
   OIDCClientSecret MIRACL_CLIENT_SECRET
   OIDCScope "openid email profile"
   OIDCProviderTokenEndpointAuth client_secret_post
   OIDCResponseType "code"
   OIDCRemoteUserClaim "sub"
   OIDCResponseMode "query"
   OIDCJWKSRefreshInterval 300
</IfModule>

You will 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 MIRACL_CLIENT_ID fill in the client ID you received from the MIRACL Trust Application setup
  • For MIRACL_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 login page.