Authentification SAMLv2 - Configuration

Last modified by Aurelie Bertrand on 2023/05/11 10:24

Summary: 

I. Prerequisites

In this document we will call:

SP: Service Provider or Service ProviderIdP: Identity Provider
  
Kpr (SP): the private key of SPKpr (IdP): the private key of the IdP
Kpb (SP): the public key of SPKpb (IdP): the public key to IdP

----------------------

Have the following items available:

  • the SP private key
  • the public key of the SP
  • the IdP public key
  • OpenSSL: a tool for handling objects used for secure connections (x509 certificates, signatures, encryption, etc.). It allows in particular the formatting of certificates.

Important  :

If both parties (SP and IdP) are expected to sign their data,

  • In particular, care should be taken to ensure that certificates with the public keys exchanged are certified by a certification authority (CA-signed certificate).
  • In the case of self-signed certificates, it will be necessary to check whether these are supported by either of the parties.

II. Principles

The actors and tools necessary for the implementation of a secure SAMLv2 communication (encrypted and / or signed) can be summarized as follows:

Service Provider
 (SP Service Provider)
CommunicationUnifying identity
 (Identity Provider IdP)
Encrypts data with Kpb (IdP)

>

The SP sends the encrypted and / or signed authentication request to the IdP

Decrypt data with Kpr (IdP)
Sign data with Kpr (SP)Valid signature with Kpb (SP)
   
Decrypt data with Kpr (SP)

<

The IdP sends the encrypted and / or signed SAMLv2 response to the SP

Encrypts data with Kpb (SP)
Valid signature with Kpb (IdP)Sign data with Kpr (IdP)

Principle: encryption and signature of the data exchanged between the SP and the IdP

The SP must therefore be aware of

- the SP private key

- the public key of the SP

- the public key of the IdP

III. Formatting of private keys

Onelogin requires PKCS # 8 format for private keys (the content of the key must start with "BEGIN PRIVATE KEY").

If you ever have a private key in PKCS # 1 format (the content of the key begins with "BEGIN RSA PRIVATE KEY"), format it by generating a new private key in the correct format using the command:

openssl pkcs8 -topk8 -inform pem -nocrypt -in sp.rsa_key -outform pem -out sp.pem

IV. Retrieving keys in a string

Onelogin provides online tools to recover keys in the form of a character string without losing the format.

IV.1 Public key

We can use the tool available via the following link to retrieve the character string corresponding to a public  key :

https://developers.onelogin.com/saml/online-tools/x509-certs/format-x509-certificate

We want to recover the public key in the following form ( WITH headers and WITHOUT carriage return ):

-----BEGIN CERTIFICATE-----XXXXXXX-----END CERTIFICATE-----

with XXXXXXX the content of the “X.509 cert in string format” section

1592386898235-169.png

Onelogin online tool: formatting an x509 certificate containing a public key

IV.2 Private key

We can use the tool available via the following link to retrieve the character string corresponding to a private key :

https://developers.onelogin.com/saml/online-tools/x509-certs/format-private-key

We want to recover the private key in the following form ( WITH headers and WITHOUT carriage return ):

-----BEGIN PRIVATE KEY-----YYYYYYY-----END PRIVATE KEY-----

with YYYYYYY the content of the “Private Key in string format” section

1592386741842-227.png

Onelogin online tool: formatting a private key

V. Overloading of properties in the security file

In the SAMLv2 security file (.properties) add the following properties:

onelogin.saml2.sp.x509cert: the certificate containing the public key of the SP

onelogin.saml2.sp.privatekey: the SP private key

onelogin.saml2.idp.x509cert: the certificate containing the IdP public key

Extract from the SAMLv2 security file overloading the properties concerning public / private keys

...

# Service Provider Data that DigDash deploys

onelogin.saml2.sp.x509cert = -----BEGIN CERTIFICATE-----XXXXXXX-----END CERTIFICATE-----
onelogin.saml2.sp.privatekey = -----BEGIN PRIVATE KEY-----YYYYYYY-----END PRIVATE KEY-----


# Identity Provider Data used to connect with DigDash (SP)

onelogin.saml2.idp.x509cert = -----BEGIN CERTIFICATE-----ZZZZZZZ-----END CERTIFICATE-----

...