# SAML flows with Humand as Identity Provider (PoC)

A [Identity Provider PoC](https://github.com/HumandDev/idp-poc) was done to demonstrate using Identity Provider initiated SAML flows with Human Identity 
Provider (Hu IdP) to open an app in a logged-in state.

This article documents the final version of the diagram that shows the flow integrated into Humand App.

## General process overview
```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Browser as Humand App
    participant Humand as Humand Api (IdP)
    participant Ext as External App (SP)

    Note over User,Ext: First the standard login flow<br/>(which can vary per community) 
    User->>+Browser: Access Humand
    Browser->>+Humand: Request login page
    Humand-->>-Browser: Redirect to login page
    Browser-->>-User: Show login page

    User->>+Browser: Enter credentials and submit
    Browser->>+Humand: Submit credentials
    Humand-->>Humand: Validate credentials
    Humand-->>-Browser: Redirect to user home
    Browser-->>-User: Show user home

    Note over User,Ext: Now the IdP-initiated SAML flow
    User->>+Browser: Click on External App link
    Browser->>+Humand: Request External App login assertion
    Humand-->>Humand: Generate and sign SAML assertion
    Humand-->>-Browser: Send SAML assertion
    Browser-->>+Ext: Post SAML assertion
    Ext-->>Ext: Authenticate using SAML assertion
    Ext-->>-Browser: Send redirect to external app user home
    Browser-->>-User: Show external app user home
```

## New endpoints for SAML flows

### IdP-initiated SAML flow
When the user clicks on an external tool link, this endpoint allows starting an IdP-initiated SAML flow. The response contains a SAMLResponse that the Web 
App needs to use to POST to the Service Provider.

```http request
GET /api/v1/auth/idp/init/:serviceProviderId
Authorization: Bearer <user bearer token>

HTTP/2 200 OK
content-type: application/json

{
  "SAMLResponse": "PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxzYW1scDpSZXNwb2 ... Cjwvc2FtbHA6UmVzcG9uc2U+"
  "acsUrl": "https://service-provider-url/auth/acs",
}
```

### SAML AuthN request
> We have not implemented this endpoint yet, it is only required for SP-initiated flows.

This is the entry point for the Service Provider to send the SAML AuthN request.

This is a POST request that contains a SAMLRequest signed by the Service Provider. Because of the nature of Humand Web App, the request will
not contain any authentication information from the user (because we are not using cookies). So the request will be stored temporarily by the backend, and
the user will be redirected to the Humand Web App to authenticate. If the user is not authenticated with Humand, they will need to log in first by 
following the login flow that corresponds to their community. Once authenticated, the Web App will submit the authentication details to the API. The API
will proceed with generating a SAMLResponse to send back to the Web App. Now the Web App will make a POST request to the service provider, completing the 
SAML flow.

```http request
POST /api/v1/auth/idp/:instanceId/sso
```