ipsilon-client-install(1)

💖 ipsilon-client-install — like, the Ipsilon client glow-up tool 💖

okay bestie, so this is ipsilon-client-install, one of the Ipsilon manual pages (yes the whole Ipsilon Manual Pages collection, we're fancy here ✨). It's the little script that turns your boring regular server into a card-carrying member of the federation. Let's get into it 🫶

---

✨ SYNOPSIS ✨

ipsilon-client-install [OPTION]...

---

🌸 DESCRIPTION 🌸

So what this does is it configures a server to be used as a Service Provider (SP) in federation with an Ipsilon instance that's acting as its Identity Provider (IdP). That's the whole vibe. 🦋

And by default? It sets up Apache using mod_auth_mellon to handle all the SAML 2 Federation stuff for you. No cap, it just does it.

---

💅 OPTIONS 💅

• -h, --help — shows you the help message and then dips. bye 👋
• --version — prints the program's version number and exits.
• --hostname HOSTNAME — the machine's fully qualified host name. yes, the whole thing.
• --port PORT — the port number your SP listens on. By default it does not set a specific listen port (so like, no port, no problem). Heads up though: the --saml-secure-setup option can mess with this one.
• --admin-user ADMIN_USER — the account that's allowed to create a Service Provider (SP). Defaults to admin.
• --admin-password ADMIN_PASSWORD — a file containing the password for the account used to create a SP. Use - to read it from stdin instead. You can also just drop the password into the IPSILON_ADMIN_PASSWORD environment variable if that's more your vibe.
• --httpd-user HTTPD_USER — the web server account that gets used. Some of the files this install creates will get chown(1)'d to this user. Default is apache.
• --saml — Boolean value, whether to install a saml2 SP or not. Default is True. (yes the flag takes a boolean, we love that for us)
• --saml-idp-url SAML_IDP_URL — a URL of the Ipsilon instance you want to register the SP with.
• --saml-idp-metadata SAML_IDP_METADATA — a URL pointing at the IDP Metadata (FILE or HTTP).
• --saml-no-httpd — do not configure httpd. Default is False.
• --saml-base SAML_BASE — where saml2 authdata is available. Default: /
• --saml-auth SAML_AUTH — where saml2 authentication gets enforced. Default is /protected. This one only applies when you're configuring Apache, fyi.
• --saml-sp SAML_SP — where saml communication happens. Default is /saml2.
• --saml-sp-logout SAML_SP_LOGOUT — the Single Logout URL. Default is /saml2/logout.
• --no-saml-soap-logout — disables Single Logout using SOAP.
• --saml-sp-post SAML_SP_POST — the Post response URL. Default is /saml2/postResponse.
• --saml-secure-setup — turns on all the security checks. Default is True. slay, honestly 🔥
• --saml-nameid — the saml2 NameID format this SP is gonna use. It must be one of: x509,transient,persistent,windows,encrypted,kerberos,email,unspecified,entity. Default is unspecified.
• --saml-sp-name SAML_SP_NAME — the SP name to register with the IdP.
• --debug — turns on script debugging. for when things are being weird 💀
• --uninstall — uninstalls the ipsilon client. rip to the SP era, it was real 🙈

---

🎀 CERTIFICATES 🎀

Two levels of SSL certificates may be used in an Ipsilon instalation. (yes, two whole levels, we're not playing around 💖)

An X509 signing certificate is what Ipsilon uses to sign SAML 2 messages. The public key of the certificate gets passed along in the SAML metadata that's exchanged between the Identity Provider and the Service Provider. This certificate and key are automatically generated — you don't gotta do a thing, it's giving self-sufficient ✨

Then there's the other one. Any page on the SP that's gonna use the authentication provided by the IdP needs to be protected by SSL, because that's how it gets to the secure cookie that the IdP provides. And here's the thing — Ipsilon does not provide this certificate. That one's on you, bestie. 😭

---

🌈 EXAMPLES 🌈

Install a SAML 2 SP using the IdP instance idp on idp.example.com:

# ipsilon-client-install --saml-idp-metadata https://idp.example.com/idp/saml2/metadata --saml-auth /protected

Any unauthenticated request to /protected will trigger a redirect to the IdP for authentication. main character redirect energy, honestly. 👑

Once the SP has been generated, it needs to be registered with the IdP. don't forget this part!! 🫶

---

⭐ EXIT STATUS ⭐

• 0 — if the installation was successful 🎉
• 1 — if an error occurred 😭

---

💜 SEE ALSO 💜

• ipsilon(7)

---

okay that's the whole page, you're officially an Ipsilon client-installation expert now, no cap 💅 this was the Ipsilon manual, version 3.0.1 — go forth and federate, bestie 🦋✨