Skip to content
line

SAML support

Para can act as a SAML service provider and connect to a specified identity provider (IDP). The implementation uses OneLogin’s SAML Java Toolkit. Here’s a summary of all the steps required to authenticate users with SAML:

  1. Generate a X509 certificate and private key for your SP
  2. Convert the private key to PKCS#8 and Base64-encode both public and private keys
  3. Specify the metadata URL for your IDP in your config file
  4. Register Para with your IDP as trusted SP by copying the metadata from /saml_metadata/{appid}
  5. Send users to /saml_auth/{appid} and Para will take care of the rest

The SP metadata endpoint is /saml_metadata/{appid} where appid is the app id for your Para app. For example, if your Para endpoint is paraio.com and your appid is myapp, then the metadata is available at https://paraio.com/saml_metadata/myapp as an XML file.

SAML authentication is initiated by sending users to the Para SAML authentication endpoint /saml_auth/{appid}. For example, if your Para endpoint is paraio.com and your appid is myapp, then the user should be sent to https://paraio.com/saml_auth/myapp. Para (the service provider) will handle the request and redirect to the SAML IDP. Finally, upon successful authentication, the user is redirected back to https://paraio.com/saml_auth/myapp which is also the assertion consumer service (ACS).

There are lots of configuration options but Para needs only a few of those in order to successfully authenticate with your SAML IDP (listed in the first rows below).

PropertyDefault valueDescription
para.security.saml.sp.entityidblankThe SP entityId, a URL in the form of https://paraio.com/saml_auth/{appid}.
para.security.saml.sp.assertion_consumer_service.urlblankThe URL where users will be redirected back to, from the IDP. Same value as the entityId above.
para.security.saml.sp.nameidformatblankSpecifies constraints on the name identifier to be used to represent the requested subject.
para.security.saml.sp.x509certblankThe X509 certificate for the SP, encoded as Base64.
para.security.saml.sp.privatekeyblankThe private key for the X509 certificate, in PKCS#8 format, encoded as Base64.
para.security.saml.idp.entityidblankThe IDP entityId, a URL in the form of https://idphost/idp/metadata.xml
para.security.saml.idp.single_sign_on_service.urlblankSSO endpoint URL of the IdP.
para.security.saml.idp.x509certblankThe x509 certificate for the IDP, encoded as Base64.
para.security.saml.idp.metadata_urlblankThe location of IDP’s metadata document. Para will fetch it and the IDP will be auto-configured.
para.security.saml.security.authnrequest_signedfalseEnables/disables signing of auth requests to the IDP.
para.security.saml.security.want_messages_signedfalseEnables/disables signing of messages to the IDP.
para.security.saml.security.want_assertions_signedfalseEnables/disables the requirement for signed assertions.
para.security.saml.security.want_assertions_encryptedfalseEnables/disables the requirement for encrypted assertions.
para.security.saml.security.want_nameid_encryptedfalseEnables/disables the requirement for encrypted nameId
para.security.saml.security.sign_metadatafalseEnables/disables signing of SP’s metadata.
para.security.saml.security.want_xml_validationtrueEnables/disables XML validation by the SP.
para.security.saml.security.signature_algorithmblankAlgorithm that the SP will use in the signing process.
para.security.saml.attributes.idblankMapping key for the id attribute.
para.security.saml.attributes.pictureblankMapping key for the picture attribute.
para.security.saml.attributes.emailblankMapping key for the email attribute.
para.security.saml.attributes.nameblankMapping key for the name attribute. If this is set, the values for attributes firstname and lastname below will be ignored.
para.security.saml.attributes.firstnameblankMapping key for the firstname attribute.
para.security.saml.attributes.lastnameblankMapping key for the lastname attribute.
para.security.saml.domainblankDomain name for users who don’t have a valid email.

As a bare minimum, you should have the following SAML configuration:

para-application.conf
# minimal setup
# IDP metadata URL, e.g. https://idphost/idp/shibboleth
para.security.saml.idp.metadata_url = ""


# SP endpoint, e.g. https://paraio.com/saml_auth/myapp
para.security.saml.sp.entityid = ""


# SP public key as Base64(x509 certificate)
para.security.saml.sp.x509cert = ""


# SP private key as Base64(PKCS#8 key)
para.security.saml.sp.privatekey = ""


# attribute mappings (usually required)
# e.g. urn:oid:0.9.2342.19200300.100.1.1
para.security.saml.attributes.id = ""
# e.g. urn:oid:0.9.2342.19200300.100.1.3
para.security.saml.attributes.email = ""
# e.g. urn:oid:2.5.4.3
para.security.saml.attributes.name = ""

You want to either configure para.security.saml.attributes.name or para.security.saml.attributes.firstname, but not both.

You can also configure the SAML authentication filter through the app settings API:

{
  "security.saml.sp.entityid": "https://paraio.com/saml_auth/myapp",
  "security.saml.idp.metadata_url": "https://idphost/idp/shibboleth",
  "security.saml.sp.x509cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0...",
  "security.saml.sp.privatekey": "LS0tLS1CRUdJTiBQUklWQVRF...",
  ...
  "signin_success": "http://success.url",
  "signin_failure": "http://failure.url"
}

Para can return a short-lived ID token back to the client which initiated the request. Add jwt=id to your signin_success url. For example { "signin_success": "http://success.url?jwt=id" }. The id value of the parameter will be replaced with the actual JWT ID token, which you can use to call paraClient.signIn("passwordless", idToken) to get the long-lived session token.

You can also put all of the settings above in a configuration file, but this only works if your app is the root app (see the config).