docs: document SP metadata generation process for SSO integration into apps

docs/saml/create-sp-metadata.md

@@ -0,0 +1,86 @@
+## Install Shibboleth
+
+repo file for RHEL `/etc/yum.repos.d/shibboleth.repo`
+
+```
+sudo su -
+cat << 'EOF' > /etc/yum.repos.d/shibboleth.repo
+[shibboleth]
+name=Shibboleth (rockylinux9)
+# Please report any problems to https://shibboleth.atlassian.net/jira
+type=rpm-md
+mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/rockylinux9
+gpgcheck=1
+gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
+enabled=1
+EOF
+```
+
+```
+yum install -y shibboleth
+```
+
+
+Start the shibd service,
+
+```
+sudo systemctl start shibd.service
+sudo systemctl enable shibd.service
+```
+
+## Verify
+
+```
+sudo LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t
+```
+
+Important is that the last line of the output is:
+```
+overall configuration is loadable, check console for non-fatal problems
+```
+
+
+## Configuration
+
+### Generate Certificate and Key for SAML message signing/encrypting
+
+The Shibboleth daemon (`shibd`) needs an X.509 keypair for signing and encrypting SAML messages. Switch recommends to use a dedicated self-signed certificate, independently configured from the SSL/TLS certificate used by the Web server. Checkout the [Certificate Overview](https://www.switch.ch/aai/certificates/) to better understand the role the certificates play in this context.  
+The web server can use any certificate for providing TLS/SSL. In addition, the Shibboleth SP also needs a keypair with a certificate for signing and decrypting messages. The Service Provider can either use the same certificate as is used for the web server (not recommended) or one can create an independent self-signed certificate with a lifetime of 10 years for usage by the Shibboleth SP only. Switch recommends to use a long-lived, self-signed certificate for usage by the Shibboleth SP.
+
+Generate the x509 certs with `keygen.sh` (Red Hat Enterprise, Rocky, CentOS):
+
+```
+sudo /etc/shibboleth/keygen.sh -f -u shibd -h <YOURHOST.EXAMPLE.ORG> -y 10 -o /etc/shibboleth/
+```
+
+### Generate the SP metadata 
+
+```
+sudo /etc/shibboleth/metagen.sh -c /etc/shibboleth/sp-cert.pem -h it-gpt.it.uab.edu > /etc/shibboleth/sp-metadata.xml
+```
+
+Check if these four attributes match with your app values 
+- entityID
+- `AssertionConsumerService`
+- <ds:X509Certificate>
+- SingleLogoutService
+
+This concludes the SP metadata generation. You can open a ticket with ASKIT and attach the metadata file you generated /etc/shibboleth/sp-metadata.xml
+
+Alternately, you can also provide them with a URL where the SP metadata is available for your app. Follow the section below for the additional configuration needed for that.
+
+## Testing
+
+### Configure shibboleth2.xml file for your SP
+
+The shibboleth2.xml file will need to be configured for your Service Provider (SP) to allow it to work with UAB's Identity Provider (IdP). The file comes with the Shibboleth SP software, and is located by default at `/etc/shibboleth/shibboleth2.xml`
+
+### Install Apache
+
+```
+yum install -y httpd
+systemctl start httpd
+systemctl enable httpd
+```
+
+### Generate SSL certs