SAML Provider configuration

The configuration depends on the Identity Provider (IdP), this is just a quick overview of what is usually needed.

Exchange of metadata

Unlike OAuth2/OIDC, where you configure client id/secret, in SAML the main integration is based on metadata files. Both sides (Service Provider — your samo authentication server, and Identity Provider) must exchange their metadata:

Identity Provider metadata

Contains IdP entity ID, SSO endpoints (login, logout), signing certificates, etc. This must be provided to the Service Provider (your samo authentication server).

Example Idp metadata:

<md:EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
                     xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                     xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                     entityID="http://localhost:8080/realms/master">
    <md:IDPSSODescriptor WantAuthnRequestsSigned="true"
                         protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <md:KeyDescriptor use="signing">
            <ds:KeyInfo>
                <ds:KeyName>Ve-v...tPo</ds:KeyName>
                <ds:X509Data>
                    <ds:X509Certificate>MII...sXe0/34=</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>

        <md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
                                      Location="http://localhost:8080/realms/master/protocol/saml/resolve"
                                      index="0"/>

        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                               Location="http://localhost:8080/realms/master/protocol/saml"/>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                               Location="http://localhost:8080/realms/master/protocol/saml"/>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
                               Location="http://localhost:8080/realms/master/protocol/saml"/>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
                               Location="http://localhost:8080/realms/master/protocol/saml"/>

        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>

        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                Location="http://localhost:8080/realms/master/protocol/saml"/>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                                Location="http://localhost:8080/realms/master/protocol/saml"/>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
                                Location="http://localhost:8080/realms/master/protocol/saml"/>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
                                Location="http://localhost:8080/realms/master/protocol/saml"/>
    </md:IDPSSODescriptor>
</md:EntityDescriptor>

Service Provider metadata

Contains SP entity ID, Assertion Consumer Service (ACS) URL, Single Logout URL, and SP certificate. This must be uploaded/imported into the IdP.

Example SP metadata:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="samo-auth-server">
    <md:SPSSODescriptor AuthnRequestsSigned="false"
                        WantAssertionsSigned="false"
                        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <md:NameIDFormat>
            urn:oasis:names:tc:SAML:2.0:nameid-format:transient
        </md:NameIDFormat>

        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                     index="1"/>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

How to prepare the certificate and key

Generate a private key and certificate

You can generate a self-signed certificate for testing or request a CA-signed certificate for production. Common tools:

• OpenSSL
• Keytool (Java)

Example using OpenSSL:

openssl req -newkey rsa:2048 -nodes -keyout sp-key.pem -x509 -days 365 -out sp-cert.pem

Import into a keystore

For Java applications (like samo authentication server), the certificate and private key are stored in a keystore (.jks or .p12):

# Convert PEM to PKCS12 keystore
openssl pkcs12 -export -in sp-cert.pem -inkey sp-key.pem -name sp-key -out keystore.p12

Use signed certificates for production

• Self-signed certificates are suitable for development/testing.
• For production, obtain a certificate from a trusted Certificate Authority (CA) to ensure other systems (IdPs) trust your SP.

Configure SP metadata to indicate signing

If your SP signs SAML requests or decrypts assertions, the default_key is used automatically. No need to manually embed keys in the metadata XML; the server reads them from the keystore.

How the data is used

• The private key is used by your SP to sign SAML requests or decrypt assertions from the IdP.
• The certificate is shared with the IdP to allow it to verify signed requests from your SP.
• Do not expose your private key publicly. Keep it secure on the server.

Authorized urls

• Usually, you need to allow origin and redirect urls for your client app (in this case samo authentication server).

Origin url

• This is the url from which the request is send.
• Many times, only the general origin is required, so the value should be just url of the root context of samo authentication server.
• If exact url is needed, the value is {$samo-auth-server-url}/auth/saml/authorize-client/{id}, where id is the custom identificator from you metadata (name of your metadat file), not the client id generated by provider.

Redirect url

• This is the url, to which provider redirects after the successfull authentication.
• The value is {$samo-auth-server-url}/auth/saml/login/code.