Introduction

SBS is a membership management portal. It allows user to define their own collaborations (rich groups), invite new users to those groups, and give this collaboration access to services.

We want to integrate this with EngineBlock, such that users get access to services based on their collaboration membership (instead of IdP-SP combinations) and that extra attributes can be added from SBS.

We will add a config option in Manage coin:collab_enabled that is true for all entities for which the checkes below need to be carried out.

Changes

This means that the following changes in EB need to be made:

• Change the ValidateAllowedConnection input filter so that collab_enabled-services skip the IdP-SP check. I.e., if coin:collab_enabled is set, skip the check if the correct IdP is connected, and always allow the flow to continue.
• Add an SBSAuthorization Filter command, which makes a backchannel call to SBS to see if the user has access to the service (see below); the call will either return status=authorized and a set of attributes, or status=interrupt to indicate a redirect to SBS is required (see below).
• If the SBS call returns authorized, add the attributes sent by SBS to the Assertion
• If the SBS call returns interrupt, then, after processing consent and stepup, redirect the user to SBS
• Add an "collab interrupt" route that receives the user when they get back from their SBS interrupt, fetches the attributes from SBS, and resumes the AuthN flow.

Flow and steps

The proposed flow is shown here:

https://editor.plantuml.com/uml/tLPTJzim57tFhxY25wZIybxn5ROnJHgZeeAdIfMJtBPMNJkphs4mxR_lscdp0OAnFIulTN8_VEx9EN7F7GbBVgCIuSbelydH9YjP8YoCeTpyI4YIGlYabr9ZhaonFffUJ45gmgKL976chol8XPCExeM6RqONw19HaB6mT-lGxe5mu7cHeEPcZx2NLPMI1HSR7OEYgffOPwCOmpmfZ2Ph5EpnnZDz8OerwZ86NUvoR4fZ-D9oTYU-mAGK91WWRZDqH1ZZzJ990ZeOdWOWOxYJJX9FK5NX4UPZo3ojD5Zyxj5HWldkkTIL9rX8HMZTJ1_S2oLvCqoviTtmpHCllvIJONQLmcWqEaoq8GGhbok21FYwsrPaIfa7B3yOhR48lFHwWqOiWGpa21jJoeN4CfPFRxAh8MgHAuvF9yoaUX2FuOVRWIXuECVqb13sJPRM-6h_ir4bo4MidVFSzxB0s2pCnOD5JiSm61on8bPFSym70vZfGD5SbYbWLUaKmZkHskFSMvNEzBPFJ93E-PWRkyPsiN5DzXXyIEhLG_q6dvKqK8eL5ciNGor_yJPS6q75AkeBcBOjJ63n1Q1Dbc0IMA6qahKMQufgLckUeCcDITk9pcfgTXJ6Lefg4lU_1Y0NocDRsuuR1B9novF0eh4iXP9v4aHMvfxGDHNF9R6x8ae6qjRtmXR9MmrjGpQihMssI-cXHiK6s9z8lNu3Qt2rjRwYT6kJ53PCZLZYk-5o70uUaGx_0BpPwYsuDvtQbsYvtbX6-bw8cOPO0gOelEsqxk_CD_oAasTswUEjlm7nynAjqaG7WxD8tCbn_3dT2Ng1S3mSlkw1cNxXWGLszY3XNhV0rMNMhBFRIQijf6BqKi0C_dZO0V-p2-JNO92yyZbefBRx9iHfjg32N6t1F_WukXDxvcpTMpkKlVeVU_FlnTv8DIoYNFlBvg2wPcPj_xZYrtSm-JX98RkP77PIfuGL5xSF-4nohCrkDq-THl6WP3rr3qfNXQBwMELGED_F6HZ_pVWD

Steps 1 and 2

No changes.

Step 3

TheValidateAllowedConnection input filter needs to be modified: if coin:collab_enabled is true, access should always be allowed, so no check if the IdP is connected to the SP should be performed. The other filters are unchanged.

Steps 4-9

A new input filter is introduced between AttributeAggregator and EnforcePolicy. A backend call to SBS is made using HTTP secured with an API token in the Authorization header. Input is a json payload:

{
 "user_id":"urn:collab:person:example.com:admin",
 "eppn": "[email protected]",
 "service_id":"https://entity_if_of_service",
 "issuer_id":"https://entity_id_of_authenticating_idp",
 "continue_url": "https://engineblock.openconext.nl/authentication/idp/process-sraminterrupt/c18307ded94fe10c41c5e7f296ac557699cec055dd52f76894cf75aa0b35166f"
}

Parameters are:

• user_id: the unique identifier (collabPersonId) for the user from the IdP. urn:mace:dir:attribute-def:uid
• eppn: an identifier for the user. eduPersonPrincipalName or empty string in EB
• service_id: entityID or client_id of real client entity, not trusted proxy
• issuer_id: entityID of IdP
• continue_url: unique URL where to receive user where they will resume their EB journey when they get back from SBS (includes a 32 byte/64 char random hex string tied to this AuthN process) (see below)

SBS returns a json payload:

{
"msg": "<authorized|interrupt|error>",
"nonce": "<uuid4>",
"message": "<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": {
  "urn:mace:dir:attribute-def:eduPersonEntitlement": ["[email protected]", "[email protected]"],
  "urn:mace:dir:attribute-def:uid": "[email protected]",
  "urn:mace:dir:attribute-def:eduPersonPrincipalName": "[email protected]",
  "urn:oid:1.3.6.1.4.1.24552.500.1.1.1.13": ["ssh_key1", "ssh_key2"]
  }
}

The fields are:

• msg: the result of the authorization check in SBS. Three values are possible:
  • authorised: user is allowed access, no redirect is necessary
  • interrupt: user has to perform tasks in SBS, redirect the the specified redirect_url (see below)
  • error: an error has occured
• nonce: uuid
• message: log message for internal use; do not show to the user
• attributes: (only if result=authorized) attributes to add to the Assertion, can be left out in case of login to SBS itself

Steps 10-11

Process the remaining input filters (PDP and ARP), and (if applicable) Stepup.

Steps 12-15

If in Step 8 status=interrupt was received, we are redirecting the browser to the configured interrupt_url with the nonce query parameter. Because the nonce is not guessable, SBS can use nonce to retrieve the user and service for which the information was exchanged in step 4.

SBS will check what exactly the user needs to do; it could simply show an error page (in which case the EB session is never resumed), or it could ask the user to agree to AUPs, perform stepup, become a member of a Collaboration, etc.

If the user is done, SBS will redirect the browser to the (unique) continue_url that was communicated by EB in step 4.

Step 16-19

We now invoke the /attributes_eb check of step 4. We expect only status=authorized now, any other status should be regarded as an error. The call is a POST with as body a JSON payload {"nonce": nonce}

The returned attributes are added to the Assertion.

Steps 20-23

Process consent, ssid step-up and the output filters en redirect the browser to the SP as usual.

Misc

Out of scope for now:

• allow exceptions for IdPs that should not be accessible using SBS
• allow either "full-IdP"-access and "per-collaboration"-access (for now, only implement that collab_enabled-SPs have access via collaboraion-memberships)

SBS user matching

• Maak een nieuwe kolom in sbs: collabpersonid (bestaat gegarandeerd voor alle EB-logins)
• API-call geeft collabPersonId (in user_id) en eppn (in eppn) door
• SBS matcht in eerst instantie op collabPersonId, indien die leeg is op schachome+home_org_uid (extracted uit de collabPersonId die SBS van EB krijgt) en als laatste fallback op eppn. In alle gevallen dat er een match is maar collabPersonId in SBS nog NULL is, vullen we in SBS collabPersonId
• Na een migratieperiode (grofweg 1 jaar) zijn alle collabpersionids gevuld en kunnen we de userstabel van SBS opruimen
  EB zorgt ervoor (bij de koppeling van EduTEAMS/MyAccessID/eduGAIN) dat alle buitenlanders ook een collabPersionID krijgen