EngineBlock integration

EB will only interact with SRAM if the SP is a SRAM-Service. SRAM-services are a different type of entity in Manage and will be included in the push to EB by Manage.

EB will interact with SRAM after the aggregation of additional attributes and before the Policy Decision Point is consulted. See https://github.com/OpenConext/OpenConext-engineblock/blob/main/library/EngineBlock/Corto/Filter/Input.php#L92

The call from EB to SRAM is a basic authentication secured backend call (e.g. server to server). If the answer from SRAM is an interrupt, then EB will redirect to the specified redirect_url with a base64 encoded XML document in the signed_user form parameter containing the uid of the user and the service identifier. The document needs to be signed in order for SRAM to verify and trust the XML content.

sequenceDiagram
    actor User
    participant SRAM Service
    participant OIDC-NG
    participant EngineBlock
    participant Identity Provider
    participant Attribute Aggregation
    participant SRAM
    participant PdP
    User->>SRAM Service: Visits
    SRAM Service->>OIDC-NG: Authorization URL
    OIDC-NG->>EngineBlock: SAML Authn Request Redirect 
    EngineBlock->>EngineBlock: Service-IdP Matrix
    EngineBlock->>EngineBlock: Show WAYF
    EngineBlock->>Identity Provider: Redirect to SingleSignOnService
    Identity Provider->>EngineBlock: SAML Authn Response
    EngineBlock->>EngineBlock: Sanitise IdP attributes 
    Note right of EngineBlock: Validations against Manage conf
    EngineBlock->>EngineBlock: Attribute manipulations
    EngineBlock->>Attribute Aggregation: ARP and User attributes 
    Note right of EngineBlock: External ARP Sources?
    Attribute Aggregation->>EngineBlock: Aggregated attributes
    EngineBlock->>SRAM: Backchannel POST with user attributes 
    Note right of EngineBlock: Is SRAM service?
    SRAM->>SRAM: Check valid User-Service 
    SRAM->>SRAM: Create response
    Note left of SRAM: Interrupt / unauthorised reason?
    SRAM->>EngineBlock: Result: authorised / interrupt / unauthorised
    Note left of SRAM: Extra user attributes returned
    EngineBlock->>SRAM: POST redirect to redirect_url if not authorised
    Note right of EngineBlock: Signed XML with user_id
    SRAM->>SRAM: agree AUP / perform 2MFA
    SRAM->>EngineBlock: Redirect back to EB continue_url
    EngineBlock->>PdP: User attributes 
    Note right of EngineBlock: PdP decision required?
    PdP->>EngineBlock: Policy decision
    EngineBlock->>EngineBlock: Apply ARP
    EngineBlock->>OIDC-NG: SAML Authn Response
    OIDC-NG->>SRAM Service: Redirect URL
    Note right of SRAM Service: code
    SRAM Service->>OIDC-NG: Token endpoint
    Note right of SRAM Service: Backend channel
    OIDC-NG->>SRAM Service: JWT token
    SRAM Service->>OIDC-NG: User Info Endpoint
    OIDC-NG->>SRAM Service: JSON User attributes
    SRAM Service->>User: 🙏🏻

Loading

Specifications:

The backchannel POST from EB to SRAM with JSON payload:

{
"user_id":"[email protected]",
"service_id":"https://entity_if_of_service",
"issuer_id":"https://entity_id_of_authenticating_idp"
}

The results from SRAM to EB:

{
"status": {
    "result": "authorized / interrupt / unauthorized",
    "redirect_url": "https://test.sram.surf.nl/interrupt?key=value",
    "error_status": "1 / 2 3 / 4 / 97 / 98 / 99 / 100 / 101",
    "info": "USER_UNKNOWN / USER_IS_SUSPENDED / SERVICE_UNKNOWN / SERVICE_NOT_CONNECTED / NEW_FREE_RIDE_USER / MISSING_ATTRIBUTES / AUP_NOT_AGREED / SERVICE_AUP_NOT_AGREED / SECOND_FA_REQUIRED"
  }
"attributes": {
    "eduPersonEntitlement": ["[email protected]", "[email protected]"],
    "eduPersonPrincipalName": ["[email protected]"],
    "uid": ["test_user"],
    "sshkey": ["ssh_key1", "ssh_key2"]
  }
}

The attributes are only included if the result equals authorized.

EB will redirect the user to the redirect_url with two form params: signed_user and continue_url. The signed_user parameter is a signed base64 encoded XML document containing the userId of the user (equal to the user_id in the first POST from EB to SRAM) and the service entity_id:

<User userId="[email protected]" serviceId="https://entity.service">
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>g9CAfB5SoD6mojjfWr7oYCmGt8k3NutZF+SOtuystlM=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
            PSlN2E25BvF7cmOTQQ5+W7XVuUKeLxEBxEfWQzu3/hp5XGe/Onvx2iT3cuA9tqrdMmnwfhOGPVFPcm9e3TMYybFKlIZQ9pF1XlEreZBbIUJNTdvOUtYxGRkNjuHhMthJpN7HZF7CIMZZA98WH7hl+EZDeaiX4MWLs6UnBHxmh/uMekW8Frk0uV2jMVYGIHnWQcW35FIE4nVqB6atHMQUTVXrbZ0cd+1WYLVBfeyn2SWrp+GPrMpsenACXah7kC/S+klXhojO73x7NDfQ1yVWPTzOPSdtKtRXymYiLQPKPSR/4uaiXa4mLBAi0NEvzMqtzMZ2M7A1VIqyVY8+EJBS0g==
        </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate>
                    MIIC/zCCAeegAwIBAgIUSeIpDb3Txu37YHhbbUVHiA3s/q4wDQYJKoZIhvcNAQEL\nBQAwDzENMAsGA1UEAwwEdGVzdDAeFw0yNDExMTQxMTI0MTRaFw0yNDExMTUxMTI0\nMTRaMA8xDTALBgNVBAMMBHRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK\nAoIBAQC+xQwIGEqM1ykFmsFszMzVMUSGyG/xJEst6O07qcgqTQf91bPPuTrx5DIa\n813Ox04gy006iD8zA6LLh607WfhGlOxT+6dx45DrF6UEeHiR5Dq/JTj9B+lF5sHf\nj8ZBt1iRrJgtmjrb4BrhdUkyHypkeTauzBeGKteJVAL1cNNO9HmtBhn+8hdSHRWB\n7p8lRu74t6vDl2vg7++WYjd73nmkCxt6J66HVdKxaZkj2phfz5Nm07I9MQIxlAKC\nAz9MjN+A/hnGG/t8Lk7IIjn58Uou1O0lBstOWTt2r5jm4cL/BgPvK+2lqJa3qo3h\n8hDOu/HgRXu04UukQuJY+OpqA8gBAgMBAAGjUzBRMB0GA1UdDgQWBBTwzTAZAkK2\n5NJmfizds6RkKRf9aDAfBgNVHSMEGDAWgBTwzTAZAkK25NJmfizds6RkKRf9aDAP\nBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQAxa0ekqBaKnz1tVR/7\nestk6MYBZzblMHA8T9HO2ae6ocayRgo85su0cO6vmkjZHEfHFNQmsxzoMMtLg0jV\nRSQqd3Vy9sxzEMQajGKOij6ggzIsQfVKwIntJnRuEjlSn9ua/IdNIBEpgVHGWLu0\n1LCoYbqCQumN+zZeIdFQwkgPg2Ibxh4PDgwyV1ju2pRJ47VTyKnZUvpdedq5nUET\nSVX4pUj3jbPsSD8C0FIA4TbGRHoaptHwpN6cRpyF4dgGZ55wsrM08dvzBOzcnaPE\nu6SUkXIDBGuZzFo2OAVXNN3GnS+iLrZ1cb+Kn2h96UWyR/EGpJVsODr5c3rR8vqK\niAhB\n
                </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
</User>

SRAM will use the configured URL of the public signing key of EB to verify the document. SRAM will not redirect the user back for authentication, but will lookup the user and perform transparant authentication by placing the user in the session.

The continue_url is the URL where SRAM will redirect the user back when the user has agreed with AUP's or performed 2FA.

Interrupt calls alternative