---
# System prepended metadata

title: SAML

---

# SAML

### 1. SAML Terminology
- <b> Principal </b>: User is trying to authenticate

- <b> Principal Identity information (PII) </b>: Metadata attached to principal (userID, email, etc.)

- <b> Identity Provider (IdP) </b>: Service that serves as the source of identity information and authentication decision.

- <b> Service Providers (SP) </b>: Services that are requesting authentication and identity information about the principal.

    ** Note: SP take authentication responses received from IdP and use that information to create and configure sessions.

- <b> Flows </b>: In SP-initiated flows, Principal starts out at the SP, are redirected to the IdP to authenticate, and are then redirected back to the SP.

- <b> Bindings </b>: Format in which data is transferred between SP and IdP.  Two most popular are <b> HTTP Redirect Binding </b> and <b> HTTP POST Binding </b>. 

- <b> HTTP Redirect Binding </b>: Transfer data using HTTP redirects and query parameters.

- <b> HTTP POST Binding </b>:  Transfer data using HTTP POST forms, this type of binding is typically used in <b> authentication responses </b> (Connect returns even password of users => stupid).

- <b> Assertions (Authentication Responses)</b>: Statements made by the IdP about the principal. 

    ** Note: Assertions are used by the service provider to create and configure sessions for a principal.
    
- <b> IdP Session </b>: Created after the Principal is authenticated using their credentials. After authentication, the Principal is able to access all apps within the managed identity organization (org) by using Single Sign-On (SSO). The IdP session is active until the Principal signs out of the org or when the session expires, based on the policies defined in the org.

- <b> Application Session (Local Session) </b>: Created by the app after the Principal is authenticated.

- <b> Local Logout </b>: The act of signing the Principal out of the app and terminating the application session. The IdP session is still active, and other application sessions aren't affected by terminating a specific local application session. Local logout is managed by the app.

- <b>Assertion Consumer Service (ACS) URL </b>: Endpoint on the SP where the IdP will redirect to with its authentication response (in our case: https://backoffice-vietnam.linecorp-beta.com/saml/login)
    
### 2. Flow of SAML

<img width="2000" src="https://i.imgur.com/Gkv5O6S.png">




### 3. Configurations

- <b> SP Configuration </b>:
    - An ACS URL has to be configured. This endpoint should be an HTTPS endpoint because it will be used to transfer PII
    - Generate and upload a signing key to be used to sign authentication requests
    - Configuration of assertions, which includes information about the principal
    
    ![](https://i.imgur.com/Gy0y6x5.png)
    
    - SP configuration can often be automatically configured by parsing metadata provided by the IdP (example as above).
    - The most important tags are <b>SingleSignOnService</b> and <b> KeyDescriptor</b>. 
    - <b>The SingleSignOnService</b> define the binding and endpoints to send authentication requests to.
    - <b>KeyDescriptor</b> contains the public key of the IdP which will be used to validate the authentication response.

- <b> Authentication Request </b>:
    - To begin the login process, the Principal typically will navigate to the SP login page, and then click on a button (e.g: Login via SSO)
    - At this point the SP will create an AuthnRequest XML document, serialize it (base64, compress, and URL encode), add it as a query parameter to the URL, and redirect the principal’s browser to the IdP login page (we are missing this).
    - The AuthnRequest is often sent using <b> HTTP Redirect Binding</b>
    - The SAMLRequest parameter is the encoded AuthnRequest, a simplified AuthnRequest follows.
    
    ![](https://i.imgur.com/b9K5ZCW.png)
    
    - The SP generates a large secure random number and inserts it into the <b>ID</b> field in the <b>AuthnRequest</b> tag. This value is also stored locally (in database) and is used to pair requests with responses from an IdP and to prevent a malicious third party from sending an unsolicited response to a request (it would not know the ID).
    - The SP should sign the AuthnRequest. The SAML signing scheme includes the signature, key used to sign the request, and information on how to calculate the signature all under the Signature tag.
    <b>** Public Key here should be the same as in the previous img </b>
    - The <b>IssueInstant</b> is used to generate that validity window for the request.
    
- <b> Authentication Response </b>: 
    - If the Principal enters their correct login credentials, the IdP will perform a 302 Redirect to the ACS URL of the SP with body containing the authentication response.
    
    ![](https://i.imgur.com/mOweovU.png)
    
    ![](https://i.imgur.com/ywscaLu.png)
    
    - When a SP receives an authentication response, it should first check if the InResponseTo attribute references an ID of an AuthnRequest that the SP actually sent
    - The <b>IssueInstant</b> attribute should be used to scope the validity window of the response.
    - The ACS URL to which the authentication response is delivered performs no authentication of the client, this is why the Signature in the authentication response must be checked to ensure the client is the IdP.
    - The <b>Status</b> tag contains the authentication result: success or failure.
    - The <b>Subjec</b> tag identifies the principal that just authenticated.
    - The <b>Conditions</b> tag defines constraints on the assertions, for example the NotBefore and NotOnOrAfter attributes define the time duration that the assertions are valid. This prevents a malicious actor from recording a valid authentication response and then replaying at a later time (perhaps after the principals account has been removed).
    
### 4. Our application (SP).
- So for authorizing users, below are what we need to provide:
    - SAML Integration:
        - spring-saml-core
        - how to integrate (still reading)
    - Session Control:
        - Self implement or using this: https://spring.io/projects/spring-session-jdbc
        - Token, ttl to control who is using our service
    - Authorize user based on SAML response:
        - Base on user id provided by SAML response, we give them corresponding role