SAML(Security Assertion Markup Language)

SAML stands for Security Assertion Markup Language. SAML can be used to perform internet based Single Sign On (SSO) for web applications. Spring security framework provides SAML libraries which can be easily configured in our application for authentication purposes. SAML involves two entities at the basic level. SAML is an open standard data format for exchanging authentication and authorization data between identity providers and service providers. 

1. IDP (Identity Provider) - Verifies the identity of the user and generates SAML assertion
2. SP(Service Provider) - Verifies the SAML assertion, logs in and will provide access to the protected resource

How SAML works - These two parties establish trust by passing XML metadata files from one to the other. SAML request and response are XML strings that are shared between IDP and SP for actual authentication. Popular IDPs are Salesforce, Okta, OneLogin and Shibboleth. 

There are two types of authentication mechanisms

1. SP-initiated SSO - User first tries to access a resource at SP and initiates the flow.
2. IDP-initiated SSO - User would login to IDP and clicks on a link to access the service provider

Lets look at the steps to configure SAML configuration in SPRING framework with prewards as SP and ssocircle as our IDP for our prototype. 

1. Spring SAML library  : spring-security-saml2-core
2. Initialize the SAML beans (Refer - SAMLAuthConfig.java)
3. Include the following to generate SP metadata on initialization
   1. <security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>
4. Spring SAML example uses ssocircle for IDP
5. Name the entity ID unique for sp metadata(Eg.web.prewards.sso)
6. Generate the SP metadata by launching
   1. http://localhost:8080/web-rewards-portal/saml/metadata
7. Import the SP metadata to the IDP(ssocircle) with whom we want to establish the trust
8. For IDP initiated Request - Request URL from SSOcircle is 
   1. https://idp.ssocircle.com/sso/idpssoinit?metaAlias=%2Fpublicidp&spEntityID=<YOUR SERVICE PROVIDER ENTITY ID>
9. IDP and SP metadata is stored in web-prewards portal application and will be referenced as ResourceProvider in the SAML configuration file. 
10. IDP initiated request would have SAML Assertion in encrypted XML format and the assertion would be validated against the local IDP metadata for status, expiration time, issuer, signature etc.  User will be authenticated when the validation is successful
11. Multiple attributes can be sent 

Keypoints for troubleshooting

1. SAML request/response can be viewed using a firefox plugin (SAMLTracer)
2. HTTP POST request (raw form) would have the saml assertion in the encrypted form. SAMLResponse_SsoCircle_encoded.txt
3. Sample_SAMLRequest.txt, Sample_SAMLResponse.txt,ssocircle-idp.xml SAML Request/Resonse are attached. 
4. Spring SAML comes with default key manager (SamlKeystore.jks). This keystore can be used to store private certificates which can be used to digitally sign messages created by SPs and decrypting the messages sent from IDP
5. Default skew time is set to 60. If you are getting errors like "Authentication is too old to be used with values", try to increase the skew time and maxAuthenticationAge value
6. SSOCircle sends the email address in Name ID parameter. SP and IDP usually communicates each other about a subject and the subject should be identified through a NAME identifier, which should be in the common format so thats easy for the other party to identify based on the format. SAML allows the following formats
   1. urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified [default] - The interpretation of the content of the element is left to individual implementations. 
   2. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
   3. urn:oasis:names:tc:SAML:2.0:nameid-format:persistent - IDP provides persistent identifiers and they are used for linking to the local accounts in SP. For example johnForAir, johnForCard has the permission for one specified services. 
   4. urn:oasis:names:tc:SAML:2.0:nameid-format:transient - IDP tells the SP that the users in the session have been grated to access the resource on SP but the identities of the users do not offer to SP actually. For example, the assertion is just like anonymity
7. SP Metadata contains SingleSignOnService and SingleLogoutService element with a binding attribute of HTTP_Redirect and HTTP_Post. Please make sure HTTP_POST is set for default for POST request
8. WantAuthnRequestsSigned flag in IDP metadata specifies that IDP wants the authentication requests it receives from SP signed.
9. AuthnRequestsSigned flag in SP metadata specifies SP would sign the authentication requests that it sends to IDP.
10. ValidUntil indicaes how long the saml metadata is valid. ValidUntil is independant of any expiry date for signing/encryption certificates. 
11. extendedMetadataDelegate.setMetadataTrustCheck(false) can be added to disable the metadata verification on launching the application
12. Multiple attributes can be added to the assertion statements if IDP needs to send multiple values 

Generating Private Key commands - For future reference

1. keytool -keystore <keystorename> -genkeypair -alias <keyname> -keypass <password>
2. keytool -list -keystore <keystorename>
3. keytool -importkeystore -srckeystore <keystorename> -destkeystore <pkcs12keystorename> -deststoretype pkcs12 -destkeypass <pkcs12keystorepassword>
4. openssl pkcs12 -in <pkcs12keystorename> -nocerts -nodes
5. keytool -export -alias ssocircle -file ssocircle.der -keystore aKeystore.jks