Adding a SAML Identity Provider
Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. It is one of the most widely-used types of identity providers due to its lack of credential sharing and ubiquity.
To integrate with a generic SAML identity provider, you will first need to gather certain parameters.
Note that only the SP-initiated SAML flow is supported.
Identity Provider Configuration Parameters
(1) Name (required)
The identity provider's "name" is a unique identifier for the identity provider within your Border0 organization. In other words, no two custom identity providers for the same Border0 organization can have the same name.
Name must start with an alphanumeric character [a-zA-Z0-9] and can only consist of alphanumeric characters and dashes ('-') - it must not include spaces.
Name is the only parameter which can not be changed after creation-time.
(2) Display Name
The identity provider's "display name" is the name that will appear on the button corresponding to the identity provider in the login page. As opposed to name, display name need-not be unique within an organization, and can be changed at will.
(3) Logo URL
The identity provider's "logo URL" is the URL of the icon that will appear on the button corresponding to the identity provider in the login page.
(4) Sign-In URL (required)
The identity provider's "sign-in URL" is the URL of the SAML service. This URL will be the target for SAML assertion requests produced by Border0.
(5) SAML Assertion Signing Certificate (required)
The identity provider's "certificate" is an X509 certificate (public key) which will be used by Border0 to verify that SAML assertion responses (received in exchange for a SAML assertion request) were issued by the holder of the private key (the SAML identity provider).
This parameter is typically referred to as the "SAMLP server public key".
(6) Request Signing
The identity provider's "request signing" setting is a boolean (true or false) value which indicates whether Border0 should cryptographically sign SAML assertion requests. This is optional in SAML, but your identity provider might be configured to require it.
We strongly recommend enabling SAML assertion request signing. Cryptographic signatures allow your identity provider to have certainty that an assertion request came from Border0 and has not been tampered-with or modified.
--
If request signing is enabled and your SAML identity provider is configured to enforce and verify signatures, you will need to configure it to expect SAML assertion requests to be signed with Border0's key.
Specifically, you will need to supply Border0's signing certificate public key to your identity provider.
(7) Request Signing Algorithm (required when request signing is enabled)
The identity provider's "request signing algorithm" setting is the algorithm that Border0 should use to sign assertion requests, one of rsa-sha256 or rsa-sha1.
We recommend selecting SHA-256 based algorithms for both request signing and request signing digests. The SHA-1 algorithm is considered to be practically broken and should only be used if your identity provider does not support SHA-256 based algorithms. For more information regarding the discouraged use of SHA-1 see:
(8) Request Signing Digest Algorithm (required when request signing is enabled)
The identity provider's "request signing digest algorithm" setting is the algorithm that Border0 should use to generate assertion request signing digests (hashes), one of sha256 or sha1.
(9) Request Protocol Binding (required)
The identity provider's "request protocol binding" setting is the protocol to use for SAML assertion requests, one of HTTP-Redirect or HTTP-POST.
(10) Request Template
The identity provider's "request template" is the template to use for building SAML assertion requests against your SAML identity provider.
This usually does not matter and can be left empty, however some SAML identity providers expect the shape of a SAML assertion request to look a certain way or include certain information. The request template is where you get to customize what Border0 sends to your SAML identity provider when authenticating users.
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
@@AssertServiceURLAndDestination@@
ID="@@ID@@"
IssueInstant="@@IssueInstant@@"
ProtocolBinding="@@ProtocolBinding@@" Version="2.0">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">@@Issuer@@</saml:Issuer>
</samlp:AuthnRequest>
Once you've gathered all of your parameters you are ready to add a new SAML 2.0 identity provider. Below are instructions for achieving this via the Border0 Portal and the Border0 CLI respectively.
You may need to configure your SAML identity provider to allow redirecting to Border0's callback/redirect URL: https://auth.border0.com/login/callback
Identity providers typically maintain an "allowlist" or a "callback URLs" list of URLs where it is allowed to redirect authenticated users to. Your IDP might require you to add the URL above to such a list in order for it to allow Border0 to authenticate users against it.
Portal Instructions
Once you've gathered the necessary parameters, you can proceed to populate the "New SAML Identity Provider" form. Clicking "Submit" will add the identity provider.
For instructions on how to find this page in the portal, see the generic instructions on Adding a Custom Identity Provider.
The "New SAML Identity Provider" form on the Border0 Portal
CLI Instructions
Once you've gathered the necessary parameters, you add your SAML identity provider with the command border0 organization idp add saml.
Request Signing Disabled Example
$ border0 organization idp add saml \
--name ACME-Corp-Auth \
--display-name "ACME Corp. Login" \
--logo-url https://avatars.githubusercontent.com/u/16856511 \
--sign-in-url https://your.saml.protocol.url/endpoint \
--certificate-filename ./path/to/samlp-public-key.pem
[WARNING] You may need to configure your SAML provider to allow the redirect URL: https://auth.border0.com/login/callback
[WARNING] You may need to configure your SAML provider to accept assertion requests signed with the certificate found at: https://auth.border0.com/pem?cert=connection
New SAML identity provider "ACME-Corp-Auth" successfully added to your organization!
Request Signing Enabled Example
$ border0 organization idp add saml \
--name ACME-Corp-Auth \
--display-name "ACME Corp. Login" \
--logo-url https://avatars.githubusercontent.com/u/16856511 \
--sign-in-url https://your.saml.protocol.url/endpoint \
--certificate-filename ./path/to/samlp-public-key.pem \
--request-signing \
--signing-algorithm rsa-sha256 \
--digest-algorithm sha256 \
[WARNING] You may need to configure your SAML provider to allow the redirect URL: https://auth.border0.com/login/callback
[WARNING] You may need to configure your SAML provider to accept assertion requests signed with the certificate found at: https://auth.border0.com/pem?cert=connection
New SAML identity provider "ACME-Corp-Auth" successfully added to your organization!
Request Template Example
$ border0 organization idp add saml \
--name ACME-Corp-Auth \
--display-name "ACME Corp. Login" \
--logo-url https://avatars.githubusercontent.com/u/16856511 \
--sign-in-url https://your.saml.protocol.url/endpoint \
--certificate-filename ./path/to/samlp-public-key.pem \
--request-signing \
--signing-algorithm rsa-sha256 \
--digest-algorithm sha256 \
--template-filename ./path/to/request-template.xml
[WARNING] You may need to configure your SAML provider to allow the redirect URL: https://auth.border0.com/login/callback
[WARNING] You may need to configure your SAML provider to accept assertion requests signed with the certificate found at: https://auth.border0.com/pem?cert=connection
New SAML identity provider "ACME-Corp-Auth" successfully added to your organization!
Updated 10 months ago