# Shibboleth Identity Provider

Steps not yet verified in the identity provider's current admin console.

Recommended protocol: SAML 2.0.

## SAML 2.0

### Connect Shibboleth Identity Provider with SAML 2.0

1. Download the KeenAuth SP metadata from **SP metadata URL** and save it on the IdP server, for example as %{idp.home}/metadata/local-metadata.xml.
2. In conf/metadata-providers.xml add a MetadataProvider with xsi:type="FilesystemMetadataProvider" and metadataFile pointing to that file. The IdP reloads it periodically (minRefreshDelay default PT30S, maxRefreshDelay default PT4H); restart the IdP to load it immediately.
3. Alternatively load the metadata over HTTP with xsi:type="FileBackedHTTPMetadataProvider" (backingFile plus metadataURL **SP metadata URL**). Add the metadata filters your policy needs, such as SignatureValidation, RequiredValidUntil and EntityRole with RetainedRole md:SPSSODescriptor.
4. The KeenAuth entity **SP entity ID** is now a verified relying party and shibboleth.DefaultRelyingParty in conf/relying-party.xml (SAML2.SSO and the other usual profiles) applies to it. By default it issues a transient NameID, which changes at every login; KeenAuth needs a persistent one (next two steps).
5. Enable persistent NameIDs: in conf/saml-nameid.properties set idp.persistentId.sourceAttribute to a stable, non-reassignable attribute, in credentials/secrets.properties set idp.persistentId.salt to a long random secret, and in conf/saml-nameid.xml uncomment \<ref bean="shibboleth.SAML2PersistentGenerator" /\> in shibboleth.SAML2NameIDGenerators.
6. Add an override bean to shibboleth.RelyingPartyOverrides: \<bean parent="RelyingPartyByName" c:relyingPartyIds="**SP entity ID**"\> with a profileConfigurations list containing \<bean parent="SAML2.SSO" p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" /\> and \<ref bean="SAML2.Logout" /\>. The IdP ignores the NameIDFormat list of the KeenAuth metadata because it includes unspecified, and an override does not inherit the default profiles, so list each profile KeenAuth uses.
7. Release the attributes: define mail, givenName and sn (optionally groups) in conf/attribute-resolver.xml from your user store, and in conf/attribute-filter.xml add an AttributeFilterPolicy with PolicyRequirementRule xsi:type="Requester" value="**SP entity ID**" and an AttributeRule permitAny="true" for each. They are sent as urn:oid:0.9.2342.19200300.100.1.3 (mail), urn:oid:2.5.4.42 (givenName) and urn:oid:2.5.4.4 (sn); map these names to email, given name and family name in KeenAuth.
8. In KeenAuth, enter the IdP entityID (idp.entityID in conf/idp.properties, the issuer in all SAML profiles) and the IdP SAML metadata, which the IdP publishes at `https://<idp host>/idp/shibboleth` (the same file as %{idp.home}/metadata/idp-metadata.xml), then run the connection test.

Values in bold are shown on the connection's page in the Admin Portal, where this guide has them filled in.